Index: trunk/anuga_core/documentation/user_manual/anuga_user_manual.tex
===================================================================
--- trunk/anuga_core/documentation/user_manual/anuga_user_manual.tex	(revision 7822)
+++ trunk/anuga_core/documentation/user_manual/anuga_user_manual.tex	(revision 7828)
@@ -1,3 +1,3 @@
-% Complete documentation on the extended LaTeX markup used for Python
+﻿% Complete documentation on the extended LaTeX markup used for Python
 % documentation is available in ''Documenting Python'', which is part
 % of the standard documentation for Python.  It may be found online
@@ -47,5 +47,5 @@
 % the rest is at your discretion.
 \authoraddress{Geoscience Australia \\
-  Email: \email{ole.nielsen@ga.gov.au}
+  Email: \email{nariman.habili@ga.gov.au}
 }
 
@@ -71,7 +71,4 @@
                 % update_anuga_user_manual.py - if not a dummy
                 % will be used.
-
-%\release{1.2}   % release version; this is used to define the
-%                % \version macro
 
 \makeindex          % tell \index to actually write the .idx file
@@ -147,5 +144,5 @@
 where the more adventurous reader might like to go.
 
-This manual describes \anuga version 1.2. To check for later versions of this manual
+This manual describes \anuga version \version. To check for later versions of this manual
 go to \url{https://datamining.anu.edu.au/anuga}.
 
@@ -153,5 +150,5 @@
 
 This manual covers only what is needed to operate the software after
-installation and configuration. It does not includes instructions
+installation and configuration. It does not include instructions
 for installing the software or detailed API documentation, both of
 which will be covered in separate publications and by documentation
@@ -632,5 +629,5 @@
 contains stage and momentum information and can be used with the
 \anuga viewer \code{anuga\_viewer} to generate a visual
-display (see Section \ref{sec:animate}). See Section \ref{sec:file formats}
+display (see Section \ref{sec:anuga_viewer}). See Section \ref{sec:file formats}
 (page \pageref{sec:file formats}) for more on NetCDF and other file
 formats.
@@ -657,5 +654,5 @@
 
 The following figures are screenshots from the \anuga visualisation
-tool \code{animate}. Figure \ref{fig:runupstart} shows the domain
+tool \code{anuga_viewer}. Figure \ref{fig:runupstart} shows the domain
 with water surface as specified by the initial condition, $t=0$.
 Figure \ref{fig:runup2} shows later snapshots for $t=2.3$ and
@@ -663,5 +660,5 @@
 on the previously dry bed.
 
-\code{animate} is described in more detail in Section \ref{sec:animate}.
+\code{anuga_viewer} is described in more detail in Section \ref{sec:anuga_viewer}.
 
 \begin{figure}[htp]
@@ -689,5 +686,5 @@
 \subsection{Overview}
 
-The next example is about waterflow in a channel with varying boundary conditions and
+The next example is about water-flow in a channel with varying boundary conditions and
 more complex topographies. These examples build on the
 concepts introduced through the \file{runup.py} in Section \ref{sec:simpleexample}.
@@ -735,5 +732,5 @@
 Defining \code{m} and \code{n} in terms of the extent as in this example provides a convenient way of
 controlling the resolution: By defining \code{dx} and \code{dy} to be the desired size of each
-hypothenuse in the mesh we can write the mesh generation as follows:
+hypotenuse in the mesh we can write the mesh generation as follows:
 
 \begin{verbatim}
@@ -760,5 +757,5 @@
 
 The following figure is a screenshot from the \anuga visualisation
-tool \code{animate} of output from this example.
+tool \code{anuga_viewer} of output from this example.
 
 \begin{figure}[htp]
@@ -823,5 +820,5 @@
 \end{verbatim}
 
-\subsection{Flow through more complex topograhies}
+\subsection{Flow through more complex topographies}
 
 Here is the code for the third version of the channel flow \file{channel3.py}:
@@ -1226,5 +1223,5 @@
 
 Now that the scenario has been run, the user can view the output in a number of ways.
-As described earlier, the user may run \code{animate} to view a three-dimensional representation
+As described earlier, the user may run \code{anuga_viewer} to view a three-dimensional representation
 of the simulation.
 
@@ -1309,5 +1306,5 @@
 Elford Reef location for each scenario (the elevation at this location is negative,
 therefore stage is the more appropriate quantity to plot). Note the large negative stage value when the slide was
-introduced. This is due to the double gaussian form of the initial surface
+introduced. This is due to the double Gaussian form of the initial surface
 displacement of the slide. By contrast, the time series for depth is shown for the onshore location of the Cairns
 Airport in Figure \ref{fig:airportboth}.
@@ -1346,15 +1343,50 @@
 \end{itemize}
 
-The listings are intended merely to give the reader an idea of what
-each feature is, where to find it and how it can be used -- they do
+\section{Documentation}\index{Documentation}
+
+The listings here are intended merely to give the reader an idea of what
+each feature is and how it can be used -- they do
 not give full specifications; for these the reader
-may consult the code. The code for every function or class contains
+may consult the programmer's guide. The code for every function or class contains
 a documentation string, or 'docstring', that specifies the precise
 syntax for its use. This appears immediately after the line
 introducing the code, between two sets of triple quotes.
 
-Each listing also describes the location of the module in which
-the code for the feature being described can be found. All modules
-are in the folder \file{inundation} or one of its subfolders, and the
+Python has a handy tool that lets you easily navigate this documentation,
+called \code{pydoc}. In Linux, it runs as a server, which serves the
+documentation up to your web browser:
+
+1. Open a terminal at your \code{anuga_source/anuga} folder
+2. Start the python documentation server with \code{pydoc -p 6767}
+3. Open a browser and type in \code{http://localhost:6767/}
+
+Now you have a real-time programmers' guide for \anuga, and an easy way to find 
+the functions you are interested in. Pydoctor and other Python doc generators
+look nicer and have graphs, etc, but pydoc works straight out of the box. 
+
+\section{Public vs Private Interface}\index{public vs private interface}
+
+To simplify the process of writing scripts, \anuga has a public API which packages
+up all the commonly-used functionality of \anuga in the one place. To use it, simply
+import the anuga module like so:
+
+\begin{verbatim}
+import anuga
+\end{verbatim}
+
+You can now use the public API like so. Note the \code{anuga.} prefix:
+
+\begin{verbatim}
+anuga.sww2dem('in.sww', 'out.asc')
+\end{verbatim}
+
+If you wish to delve "under the hood" and modify the way \anuga runs at a more
+advanced level, you need to specify the full location of the module like so:
+
+\begin{verbatim}
+from anuga.fit_interpolate.interpolate import Interpolation_interface
+\end{verbatim}
+
+All modules are in the folder \file{inundation} or one of its subfolders, and the
 location of each module is described relative to \file{inundation}. Rather
 than using pathnames, whose syntax depends on the operating system,
@@ -1378,16 +1410,12 @@
 
 Rather than using either of these forms, in this chapter we specify
-the location simply as \code{pmesh.mesh_interface}, in keeping with
+the location simply as \code{anuga.pmesh.mesh_interface}, in keeping with
 the usage in the Python statement for importing the function,
 namely:
 
 \begin{verbatim}
-from pmesh.mesh_interface import create_mesh_from_regions
-\end{verbatim}
-
-Each listing details the full set of parameters for the class or
-function; however, the description is generally limited to the most
-important parameters and the reader is again referred to the code
-for more details.
+from anuga.pmesh.mesh_interface import create_mesh_from_regions
+\end{verbatim}
+
 
 The following parameters are common to many functions and classes
@@ -1488,15 +1516,17 @@
 
 \begin{funcdesc}{create_mesh_from_regions}{bounding_polygon,
-                                           boundary_tags,
-                                           maximum_triangle_area=None,
-                                           filename=None,
-                                           interior_regions=None,
-                                           interior_holes=None,
-                                           poly_geo_reference=None,
-                                           mesh_geo_reference=None,
-                                           minimum_triangle_angle=28.0,
-                                           fail_if_polygons_outside=True,
-                                           use_cache=False,
-                                           verbose=True}
+                                             boundary_tags,
+                                             maximum_triangle_area=None,
+                                             filename=None,
+                                             interior_regions=None,
+                                             interior_holes=None,
+                                             hole_tags=None,
+                                             poly_geo_reference=None,
+                                             mesh_geo_reference=None,
+                                             minimum_triangle_angle=28.0,
+                                             fail_if_polygons_outside=True,
+                                             breaklines=None,
+                                             use_cache=False,
+                                             verbose=True}
 Module: \module{pmesh.mesh\_interface}
 
@@ -1510,4 +1540,12 @@
 interior polygon and its resolution.  Additionally, the user specifies
 a list of boundary tags, one for each edge of the bounding polygon.
+
+\code{breaklines} lets you force a split along a boundary within the mesh. For
+example, a kerb or the edge of a dyke could be specified here. (new in 1.2)
+
+\code{interior_holes} lets you specify polygons as empty holes in the mesh.
+This can be used  to represent buildings, pylons and other immovable
+structures. These polygons do not need to be closed, but their points must be
+specified in a counter-clockwise order.(new in 1.2)
 
 \textbf{WARNING}. Note that the dictionary structure used for the
@@ -1523,5 +1561,6 @@
 
 \textbf{WARNING}. Do not have polygon lines cross or be on-top of each
-    other. This can result in regions of unspecified resolutions. Do
+    other. This can result in regions of unspecified resolutions, and \anuga
+    will give you an error. Do
     not have polygon close to each other. This can result in the area
     between the polygons having small triangles.  For more control
@@ -1559,4 +1598,9 @@
 \code{maximum_triangle_area} is the maximal area per triangle
 for the bounding polygon, excluding the interior regions.
+
+\code{interior_holes} lets you specify polygons as empty holes in the mesh.
+This can be used  to represent buildings, pylons and other immovable
+structures. These polygons do not need to be closed, but their points must be
+specified in a counter-clockwise order.(new in 1.2)
 
 \code{mesh_filename} is the name of the file to contain the generated 
@@ -2163,5 +2207,5 @@
 
 # Add buildings from file
-building_polygons, building_heights = csv2building_polygons(building_file)
+building_polygons, building_heights = anuga.load_csv_as_building_polygons(building_file)
 
 B = []
@@ -2224,4 +2268,5 @@
                                 time_limit=None,
                                 verbose=False,
+                                output_centroids=False,
                                 use_cache=False,
                                 boundary_polygon=None}
@@ -2249,4 +2294,7 @@
 This must be the same polygon as used when calling \code{create_mesh_from_regions()}.
 This argument can only be used when reading boundary data from an STS format file.
+
+\code{output_centroids} set to true to sample at the centre of the triangle containing the point.
+This may be useful for debugging. (new in 1.2)
 
 The model time stored within the file function can be accessed using
@@ -2701,5 +2749,5 @@
 \end{itemize}
 
-The user can specify different culvert routines. Hower \anuga currently provides only one, namely the
+The user can specify different culvert routines. However, \anuga currently provides only one, namely the
 \code{boyd_generalised_culvert_model} as used in the example below:
 
@@ -3112,4 +3160,5 @@
                                  time_min=None,
                                  time_max=None,
+                                 output_centroids=False,
                                  time_thinning=1,
                                  time_unit=None,
@@ -3135,4 +3184,7 @@
 
 \code{filename} is the path to the SWW file.
+
+\code{output_centroids} set to true to sample at the centre of the triangle containing the point.
+This may be useful for debugging. (new in 1.2)
 
 \code{polyline} is the representation of the desired cross section -- it may contain
@@ -3235,5 +3287,5 @@
   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 \code{animate}\\
+  TSH $\rightarrow$ SWW & Convert TSH to \code{.sww}-viewable using \code{anuga_viewer}\\
   TSH + Boundary SWW $\rightarrow$ SWW & Simulation using \code{\anuga}\\
   Polygonal mesh outline $\rightarrow$ & TSH or MSH
@@ -3259,7 +3311,7 @@
 \end{itemize}
 
-The contents of an SWW file may be viewed using the anuga viewer \code{animate},
-which creates an on-screen visialisation.  See section \ref{sec:animate}
-(page \pageref{sec:animate}) in Appendix \ref{ch:supportingtools} for more on \code{animate}.
+The contents of an SWW file may be viewed using the anuga viewer \code{anuga_viewer},
+which creates an on-screen visualisation.  See section \ref{sec:anuga_viewer}
+(page \pageref{sec:anuga_viewer}) in Appendix \ref{ch:supportingtools} for more on \code{anuga_viewer}.
 
 Alternatively, there are tools, such as \code{ncdump}, that allow
@@ -3617,5 +3669,5 @@
 
 In the computations presented in this paper we use an explicit Euler
-time stepping method with variable timestepping adapted to the
+timestepping method with variable timestepping adapted to the
 observed CFL condition:
 
@@ -3642,5 +3694,5 @@
 To alleviate the problems associated with numerical instabilities due to
 small water depths near a wet/dry boundary we employ a new flux limiter that
-ensures that unphysical fluxes are never encounted.
+ensures that unphysical fluxes are never encountered.
 
 Let $u$ and $v$ be the velocity components in the $x$ and $y$ direction,
@@ -3690,5 +3742,5 @@
   h_0 = H_0^2
 \]
-provides a reasonable balance between accurracy and stability. In fact,
+provides a reasonable balance between accuracy and stability. In fact,
 setting $h=H_0$ will scale the predicted speed by a factor of $0.5$:
 \[
@@ -3876,5 +3928,5 @@
 %%
 %
-%Sub directories contain scrips and derived files for each simulation.
+%Sub directories contain scripts and derived files for each simulation.
 %The directory ../source_data contains large source files such as
 %DEMs provided externally as well as MOST tsunami simulations to be used
@@ -3882,5 +3934,5 @@
 %
 %Manual steps are:
-%  Creation of DEMs from argcview (.asc + .prj)
+%  Creation of DEMs from arcview (.asc + .prj)
 %  Creation of mesh from pmesh (.tsh)
 %  Creation of tsunami simulations from MOST (.nc)
@@ -3967,5 +4019,5 @@
 \pagebreak
 \section{anuga\_viewer}
-\label{sec:animate}
+\label{sec:anuga_viewer}
 
 The output generated by \anuga may be viewed by
@@ -3989,5 +4041,5 @@
 %\code{anuga\_viewer} executable file (or a shortcut to it), or set up a
 %file association to make files with the extension \code{.sww} open
-%with \code{animate}. Alternatively, you can operate \code{animate}
+%with \code{anuga_viewer}. Alternatively, you can operate \code{anuga_viewer}
 %from the command line.
 
@@ -3996,17 +4048,17 @@
 
 %% \pagebreak
-%% \section{\anuga viewer -- animate}
-%% \label{sec:animate}
+%% \section{\anuga viewer -- anuga_viewer}
+%% \label{sec:anuga_viewer}
 
 %% The output generated by \anuga may be viewed by
-%% means of the visualisation tool \code{animate}, which takes an
+%% means of the visualisation tool \code{anuga_viewer}, which takes an
 %% SWW file generated by \anuga and creates a visual representation
 %% of the data. Examples may be seen in Figures \ref{fig:runupstart}
 %% and \ref{fig:runup2}. To view an SWW file with
-%% \code{animate} in the Windows environment, you can simply drag the
+%% \code{anuga_viewer} in the Windows environment, you can simply drag the
 %% icon representing the file over an icon on the desktop for the
-%% \code{animate} executable file (or a shortcut to it), or set up a
+%% \code{anuga_viewer} executable file (or a shortcut to it), or set up a
 %% file association to make files with the extension \code{.sww} open
-%% with \code{animate}. Alternatively, you can operate \code{animate}
+%% with \code{anuga_viewer}. Alternatively, you can operate \code{anuga_viewer}
 %% from the command line.
 
@@ -4034,7 +4086,7 @@
 %% % \vfill
 
-%% The following describes how to operate \code{animate} from the command line:
-
-%% Usage: \code{animate [options] swwfile \ldots}\\ \nopagebreak
+%% The following describes how to operate \code{anuga_viewer} from the command line:
+
+%% Usage: \code{anuga_viewer [options] swwfile \ldots}\\ \nopagebreak
 %% where: \\ \nopagebreak
 %% \begin{tabular}{ll}
@@ -4974,5 +5026,5 @@
   \indexedbold{stage} & &\\
 %  \indexedbold{try this}
-  \indexedbold{animate} & visualisation tool used with \anuga & \pageref{sec:animate}\\
+  \indexedbold{anuga_viewer} & visualisation tool used with \anuga & \pageref{sec:anuga_viewer}\\
   \indexedbold{time boundary} & Returns values for the conserved quantities as a function of time.
                                 The user must specify the domain to get access to the model time.
Index: trunk/anuga_core/documentation/user_manual/copyright.tex
===================================================================
--- trunk/anuga_core/documentation/user_manual/copyright.tex	(revision 7822)
+++ trunk/anuga_core/documentation/user_manual/copyright.tex	(revision 7828)
@@ -19,5 +19,5 @@
 \vspace*{0.5in}
 
-Copyright \copyright 2004, 2005, 2006 Australian National University and Geoscience Australia. All rights reserved.
+Copyright \copyright 2004, 2005, 2006, 2010 Australian National University and Geoscience Australia. All rights reserved.
 
 Permission to use, copy, modify, and distribute this software for any
@@ -134,5 +134,5 @@
 \pagebreak
 \item Pmw is a toolkit for building high-level compound widgets in
-Python using the Tkinter module. Parts of Pmw have been encorpoated
+Python using the Tkinter module. Parts of Pmw have been incorpoated
 into the graphical mesh generator. The license for Pmw reads
 
