--- MITgcm_contrib/gmaze_pv/Contents.m	2006/06/15 15:20:34	1.1
+++ MITgcm_contrib/gmaze_pv/Contents.m	2006/06/16 21:09:16	1.3
@@ -1,21 +1,74 @@
-% MITgcm_contrib Matlab routines of Guillaume MAZE
+% -----------------------------------------------------------------
+% MITgcm_contrib > G. MAZE contribution > Matlab routines
+%
+% This package tries to provide some useful and simple routines to
+% compute, visualize and analyze Potential Vorticity from the 
+% global high resolution (1/8deg) simulation of the MITgcm.
+% Routines are as general as possible for extended applications, but
+% note that they were developped to focus on the Western Atlantic
+% region for the CLIMODE project.
+% Enjoy !
 %
-% Last update: 14/06/2006
 % gmaze@mit.edu
 %
+% -----------------------------------------------------------------
+% PROGRAMS LIST (NOT FUNCTIONS):
+%
+% MAIN_GETPV
+% This program defines the global setup and launch the PV computing.
+%
+% -----------------------------------------------------------------
 % FUNCTIONS LIST:
 %
+% A_COMPUTE_POTENTIAL_DENSITY(SNAPSHOT)
+% From netcdf files contained into the SNAPSHOT directory of the
+% ./netcdf-files/ home folder, this function computes potential 
+% density from potential temperature THETA and anomalous salinity 
+% SALTanom
+%
+% B_COMPUTE_RELATIVE_VORTICITY(SNAPSHOT)
+% From netcdf files contained into the SNAPSHOT directory of the
+% ./netcdf-files/ home folder, this function computes the three
+% components of the relative vorticity from horizontal flow UVEL
+% and VVEL.
+%
+% C_COMPUTE_POTENTIAL_VORTICITY(SNAPSHOT,[WANT_SPL_PV])
+% From netcdf files contained into the SNAPSHOT directory of the
+% ./netcdf-files/ home folder, this function computes the 
+% potential vorticity field from the relative vorticity components
+% and the potential density field. Option WANT_SPL_PV turned 1 
+% makes the function only computing the PV based on the planetary 
+% vorticity.
+%
 % VOLBET2ISO(TRACER,LIMITS,DEPTH,LAT,LONG)
-% This function computes the volume limited northward by 
-% two tracer values and eastward, westward and southward
+% This function computes the volume embedded between two
+% iso-TRACER values and limited eastward, westward and southward
 % by fixed limits.
-% Very simple test available with: VOLBET2ISO_TEST
+% Very simple test available with: TEST_VOLBET2ISO
 %
 % SURFBET2OUTCROPS(TRACER,LIMITS,LAT,LONG)
-% This functions computes the horinzontal surface limited
+% This function computes the horizontal surface limited
 % by two outcrops of a tracer.
-% Very simple test available with: SURFBET2OUTCROPS_TEST
+% Very simple test available with: TEST_SURFBET2OUTCROPS
+%
+% INTBET2OUTCROPS(TRACER,LIMITS,LAT,LONG)
+% This function computes the horizontal surface integral
+% of the field TRACER on the area limited by two outcrops.
+% Very simple test available with: TEST_INTBET2OUTCROPS
+%
+% -----------------------------------------------------------------
+% LOWER LEVEL FUNCTIONS LIST:
+%
+% PV_CHECKPATH
+% This function, systematicaly called by the others, ensures that 
+% all needed sub-directories of the package are in the path.
 %
+% -----------------------------------------------------------------
+% PS:
 %
+% > Several functions use the m_map package.
+%   Ensure to get it in the Matlab path.
+%   (M_MAP is available at: http://www.eos.ubc.ca/~rich/map.html)
 %
+% -----------------------------------------------------------------
 %