Index: /documentation/user_manual/anuga_user_manual.tex
===================================================================
--- /documentation/user_manual/anuga_user_manual.tex	(revision 2466)
+++ /documentation/user_manual/anuga_user_manual.tex	(revision 2467)
@@ -41,5 +41,5 @@
 %\makemodindex          % If this contains a lot of module sections.
 
-
+\setcounter{tocdepth}{3}
 
 \begin{document}
@@ -62,9 +62,8 @@
 \begin{abstract}
 
-\noindent
-\anuga\index{AnuGA} is a hydrodynamic modelling tool that
-allows users to model realistic flow problems in complex
-geometries. Examples include dam breaks or the effects of natural
-hazards such as riverine flooding, storm surges and tsunami.
+\noindent \anuga\index{\anuga} is a hydrodynamic modelling tool that
+allows users to model realistic flow problems in complex geometries.
+Examples include dam breaks or the effects of natural hazards such
+as riverine flooding, storm surges and tsunami.
 
 The user must specify a study area represented by a mesh of triangular
@@ -514,9 +513,8 @@
 to geographic or other features in the landscape, whose presence may
 require us to vary the resolution in the neighbourhood of the
-features. However, this capability is in fact also provided in
-\code{pmesh}. It provides for these more general situations by
-allowing the user to specify a number of \emph{interior polygons},
-which are triangulated separately, each according to a separately
-specified resolution. See Figure XXX.
+features. To cope with this requirement, \code{pmesh} also allows
+the user to specify a number of \emph{interior polygons}, which are
+triangulated separately, each according to a separately specified
+resolution. See Figure XXX.
 
 In its general form, \code{pmesh} takes for its input a bounding
@@ -543,7 +541,8 @@
 file, with extension \code{.tsh}. In the present case, the binary
 file format \code{.msh} is used. See Section \ref{sec:file formats}
-for more on file formats.) \code{pmesh} assigns a name to the file
-by appending the extension \code{.msh} to the name specified in the
-input file \code{project.py}. This name is stored in the variable
+(p. \pageref{sec:file formats}) for more on file formats.)
+\code{pmesh} assigns a name to the file by appending the extension
+\code{.msh} to the name specified in the input file
+\code{project.py}. This name is stored in the variable
 \code{meshname}.
 
@@ -699,11 +698,15 @@
 \end{verbatim}}
 
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
 \chapter{\anuga Public Interface}
 
-This chapter lists the functions and classes available at the public interface.
+This chapter describes the features of \anuga that are available to
+the user at the public interface.
 
 \section{Functions and Classes}
 
-\indexedcodeheader{create\_mesh\_from\_region}\label{codehdr:create\_mesh\_from\_region}
+\indexedcodeheader{create\_mesh\_from\_regions}\label{codehdr:createmeshfromregions}
 
   Creates a triangular mesh based on a bounding polygon and
@@ -723,6 +726,28 @@
   \end{itemize}
 
-
-\indexedcodeheader{pmesh\_to\_domain\_instance}
+*********************************************************************************************
+
+\emph{\textbf{[The following is how the description of
+\emph{\code{create\_mesh\_from\_regions}} would be presented using
+the Python documentation system's \emph{\code{funcdesc}} environment
+for describing a module-level function.]}}
+
+\begin{funcdesc}  {create\_mesh\_from\_regions}{bounding_polygon,
+                             boundary_tags,
+                             maximum_triangle_area,
+                             filename=None,
+                             interior_regions=None,
+                             poly_geo_reference=None,
+                             mesh_geo_reference=None,
+                             minimum_triangle_angle=28.0}
+Creates a triangular mesh based on a bounding polygon and a number
+of internal polygons. For each polygon the user specifies a
+resolution---that is, the maximal area of triangles in the mesh. The
+bounding polygon also has symbolic \code{tags} associated with it.
+\end{funcdesc}
+
+*********************************************************************************************
+
+\indexedcodeheader{pmesh\_to\_domain\_instance}  \nopagebreak
 
  Converts a generated mesh file to a domain object.
@@ -733,5 +758,7 @@
     \item \code{file\_name} is the name of the mesh file to convert, including the extension
     \item \code{DomainClass} is the Class that will be returned.
-    It must be a subclass of \code{Domain}, with the same interface as domain.
+    It must be a subclass of \code{Domain}, with the same interface as
+    domain. In practice, it can usually be set simply to
+    \code{Domain}.
     \item \code{use\_cache}: \code{True} means that caching is attempted for the computed domain.
   \end{itemize}
@@ -743,5 +770,22 @@
   \end{itemize}
 
-\indexedcodeheader{file\_function} %in util.py "High priority"
+*********************************************************************************************
+
+\begin{funcdesc}  {pmesh\_to\_domain\_instance}{file_name, DomainClass, use_cache = False, verbose = False}
+Converts a generated mesh file to a domain object.
+
+\begin{itemize}
+    \item \code{file\_name} is the name of the mesh file to convert, including the extension
+    \item \code{DomainClass} is the Class that will be returned.
+    It must be a subclass of \code{Domain}, with the same interface as
+    domain. In practice, it can usually be set simply to
+    \code{Domain}.
+    \item \code{use\_cache}: \code{True} means that caching is attempted for the computed domain.
+  \end{itemize}
+\end{funcdesc}
+*********************************************************************************************
+
+
+%\indexedcodeheader{file\_function} %in util.py "High priority"
 
   Reads the time history of spatial data from NetCDF file and returns a callable object.
@@ -784,4 +828,27 @@
     \code{use\_cache}: \code{True} means that caching of intermediate result of
                \code{Interpolation\_function} is attempted
+
+
+  \begin{funcdesc}{file_function}{filename,
+                  domain = None,
+                  quantities = None,
+                  interpolation_points = None,
+                  verbose = False,
+                  use_cache = False}
+
+  Reads the time history of spatial data from NetCDF file and returns a callable object. Returns
+  interpolated values based on the input file
+  using the underlying \code{interpolation\_function}. 
+
+    \code{quantities} -- the name of the quantity to be interpolated or a
+                 list of quantity names. The resulting function will return
+                 a tuple of values -- one for each quantity.
+
+    \code{interpolation\_points} -- list of absolute UTM coordinates for points at
+    which values are sought
+
+    \code{use\_cache}: \code{True} means that caching of intermediate result of
+               \code{Interpolation\_function} is attempted
+  \end{funcdesc}
 
 
@@ -923,51 +990,70 @@
 \label{sec:file formats}
 
-This module takes care of reading and writing datafiles such as
-topograhies, model output, etc
-
-
-Formats used within AnuGA:
-
-.sww: Netcdf format for storing model output f(t,x,y) .tms: Netcdf
-format for storing time series f(t)
-
-.xya: ASCII format for storing arbitrary points and associated
-attributes .pts: NetCDF format for storing arbitrary points and
-associated attributes
-
-.asc: ASCII format of regular DEMs as output from ArcView .prj:
-Associated ArcView file giving more meta data for asc format .ers:
-ERMapper header format of regular DEMs for ArcView
-
-.dem: NetCDF representation of regular DEM data
-
-.tsh: ASCII format for storing meshes and associated boundary and
-region info .msh: NetCDF format for storing meshes and associated
-boundary and region info
-
-.nc: Native ferret NetCDF format .geo: Houdinis ascii geometry
-format (?)
-
-
-A typical dataflow can be described as follows
-
-Manually created files: ASC, PRJ:     Digital elevation models
-(gridded) TSH:          Triangular meshes (e.g. created from pmesh)
-NC            Model outputs for use as boundary conditions (e.g from
-MOST)
-
-
-AUTOMATICALLY CREATED FILES:
-
-ASC, PRJ  ->  DEM  ->  PTS: Conversion of DEM's to native pts file
-
-NC -> SWW: Conversion of MOST bundary files to boundary sww
-
-PTS + TSH -> TSH with elevation: Least squares fit
-
-TSH -> SWW:  Conversion of TSH to sww viewable using Swollen
-
-TSH + Boundary SWW -> SWW: Simluation using pyvolution
-
+\anuga makes use of a number of different file formats. The
+following table lists all these formats, which are described in more
+detail in the paragraphs below.
+
+\begin{tabular}{|ll|}  \hline
+\code{.sww} & NetCDF format for storing model output
+\code{f(t,x,y)}\\
+
+\code{.tms} & NetCDF format for storing time series \code{f(t)}\\
+
+\code{.xya} & ASCII format for storing arbitrary points and
+associated attributes\\
+
+\code{.pts} & NetCDF format for storing arbitrary points and
+associated attributes\\
+
+\code{.asc} & ASCII format of regular DEMs as output from ArcView\\
+
+\code{.prj} & Associated ArcView file giving more metadata for
+\code{.asc} format\\
+
+\code{.ers} & ERMapper header format of regular DEMs for ArcView\\
+
+\code{.dem} & NetCDF representation of regular DEM data\\
+
+\code{.tsh} & ASCII format for storing meshes and associated
+boundary and region info\\
+
+\code{.msh} & NetCDF format for storing meshes and associated
+boundary and region info\\
+
+\code{.nc} & Native ferret NetCDF format\\
+
+\code{.geo} & Houdinis ASCII geometry format (?) \\  \par \hline
+%\caption{File formats used by \anuga}
+\end{tabular}
+
+
+A typical dataflow can be described as follows:
+
+\subsection{Manually Created Files}
+
+\begin{tabular}{ll}
+ASC, PRJ & Digital elevation models (gridded)\\
+TSH & Triangular
+meshes (e.g. created from \code{pmesh})\\
+NC & Model outputs for use as boundary conditions (e.g. from MOST)
+\end{tabular}
+
+\subsection{Automatically Created Files}
+
+\begin{tabular}{ll}
+ASC, PRJ  $\rightarrow$  DEM  $\rightarrow$  PTS & Convert
+DEMs to native \code{.pts} file\\
+
+NC $\rightarrow$ SWW & Convert MOST boundary files to
+boundary \code{.sww}\\
+
+PTS + TSH $\rightarrow$ TSH with elevation & Least squares fit\\
+
+TSH $\rightarrow$ SWW & Convert TSH to \code{.sww}-viewable using
+Swollen\\
+
+TSH + Boundary SWW $\rightarrow$ SWW & Simulation using
+\code{pyvolution}
+\end{tabular}
 
 %\[
@@ -1221,22 +1307,22 @@
 \chapter{Glossary}
 
+\indexplacer{try it} \indexascode{try it out again}
+
 \begin{itemize}
     \item \indexedbold{\anuga} Name of software (joint development between ANU and GA)
 
-    \item \indexedbold{Conserved quantity}
-
-    \item \indexedbold{Domain}
+    \item \indexedbold{domain}
 
     \item \indexedbold{Dirichlet boundary}
 
-    \item \indexedbold{Elevation} - refers to bathymetry and topography
-
-    \item \indexedbold{Bathymetry} offshore
-
-    \item \indexedbold{Topography} onshore
-
-    \item \indexedbold{Evolution} integration of the shallow water wave equations over time
-
-    \item \indexedbold{Forcing term}
+    \item \indexedbold{elevation} - refers to bathymetry and topography
+
+    \item \indexedbold{bathymetry} offshore
+
+    \item \indexedbold{topography} onshore
+
+    \item \indexedbold{evolution} integration of the shallow water wave equations over time
+
+    \item \indexedbold{forcing term}
 
     \item \indexedbold{IDLE} Development environment shipped with Python
@@ -1244,13 +1330,13 @@
     \item \indexedbold{Manning friction coefficient}
 
-    \item \indexedbold{Mesh}    Triangulation of domain
-
-    \item \indexedbold{Meshfile}  [generic word for either .tsh or
+    \item \indexedbold{mesh}    Triangulation of domain
+
+    \item \indexedbold{meshfile}  [generic word for either .tsh or
     .msh file]
 
-    \item \indexedbold{Points file}  [generic word for either .pts or
+    \item \indexedbold{points file}  [generic word for either .pts or
     .xya file]
 
-    \item \indexedbold{Grid} evenly spaced
+    \item \indexedbold{grid} evenly spaced
 
     \item \indexedbold{NetCDF}
@@ -1260,17 +1346,19 @@
     \item \indexedbold{pyvolution} does this really need to be here? it's a class/module?
 
-    \item \indexedbold{Conserved Quantity} conserved (state, x and y momentum)
-
-    \item \indexedbold{Reflective boundary}
-
-    \item \indexedbold{Smoothing} is this really needed?
-
-    \item \indexedbold{Stage}
-
-    \item \indexedbold{Swollen} visualisation tool
-
-    \item \indexedbold{Time boundary} defined in the manual (flog from there)
-
-    \item \indexedbold{Transmissive boundary} defined in the manual (flog from there)
+    \item \indexedbold{conserved quantity} conserved (state, x and y momentum)
+
+    \item \indexedbold{reflective boundary}
+
+    \item \indexedbold{smoothing} is this really needed?
+
+    \item \indexedbold{stage}
+
+%    \item \indexedbold{try this}
+
+    \item \indexedbold{swollen} visualisation tool
+
+    \item \indexedbold{time boundary} defined in the manual (flog from there)
+
+    \item \indexedbold{transmissive boundary} defined in the manual (flog from there)
 
     \item \indexedbold{xmomentum} conserved quantity (note, two-dimensional SWW equations say only x and y and NOT z)
@@ -1278,7 +1366,7 @@
     \item \indexedbold{ymomentum}  conserved quantity
 
-    \item \indexedbold{Resolution}   The maximal area of a triangular cell in a mesh
-
-    \item \indexedbold{Polygon} A sequence of points in the plane. (Arbitrary polygons can be created
+    \item \indexedbold{resolution}   The maximal area of a triangular cell in a mesh
+
+    \item \indexedbold{polygon} A sequence of points in the plane. (Arbitrary polygons can be created
     in this way.)
     \anuga represents a polygon in one of two ways. One way is to represent it as a
@@ -1291,19 +1379,19 @@
     NOTE: More can be read in the module utilities/polygon.py ....
 
-    \item \indexedbold{Easting}
-
-    \item \indexedbold{Northing}
-
-    \item \indexedbold{Latitude}
-
-    \item \indexedbold{Longitude}
-
-    \item \indexedbold{Edge}
-
-    \item \indexedbold{Vertex}
-
-    \item \indexedbold{Finite volume}
-
-    \item \indexedbold{Flux}
+    \item \indexedbold{easting}
+
+    \item \indexedbold{northing}
+
+    \item \indexedbold{latitude}
+
+    \item \indexedbold{longitude}
+
+    \item \indexedbold{edge}
+
+    \item \indexedbold{vertex}
+
+    \item \indexedbold{finite volume}
+
+    \item \indexedbold{flux}
 
     \item \indexedbold{Digital Elevation Model (DEM)}
