--- MITgcm_contrib/gmaze_pv/Contents.m	2006/06/15 22:15:55	1.2
+++ MITgcm_contrib/gmaze_pv/Contents.m	2006/06/16 21:09:16	1.3
@@ -1,13 +1,48 @@
-% 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 !
 %
 % 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: TEST_VOLBET2ISO
 %
@@ -21,9 +56,19 @@
 % 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.
-% Be sure to get it in the Matlab path.
-% (M_MAP is available at: http://www.eos.ubc.ca/~rich/map.html)
+%
+% > 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)
+%
+% -----------------------------------------------------------------
 %