doc: Improve Tex output for vector calculus functions.

* curl.m, del2.m, divergence.m: Redo Tex format codes to improve output.

* gradient.m: Rewrite documentation to clarify how numerical gradient is calculated.

Author: Rik

scripts/general/curl.m

@@ -32,7 +32,7 @@
 ## Calculate curl of vector field given by the arrays @var{fx}, @var{fy}, and
 ## @var{fz} or @var{fx}, @var{fy} respectively.
 ## @tex
-## $$ curl F(x,y,z) = \left( {\partial{F_z} \over \partial{y}} - {\partial{F_y} \over \partial{z}}, {\partial{F_x} \over \partial{z}} - {\partial{F_z} \over \partial{x}}, {\partial{F_y} \over \partial{x}} - {\partial{F_x} \over \partial{y}} \right)$$
+## $$ {\rm curl \ {\bf F}}(x,y,z) \equiv \nabla \times {\rm \bf F} = \left( \frac{\partial{F_z}}{\partial{y}} - \frac{\partial{F_y}}{\partial{z}}, \frac{\partial{F_x}}{\partial{z}} - \frac{\partial{F_z}}{\partial{x}}, \frac{\partial{F_y}}{\partial{x}} - \frac{\partial{F_x}}{\partial{y}} \right)$$
 ## @end tex
 ## @ifnottex
 ##

scripts/general/del2.m

@@ -36,9 +36,9 @@
 ## operator.
 ## @end ifnottex
 ##
-## For a 2-dimensional matrix @var{M} this is defined as
+## For a 2-dimensional matrix @math{M(x, y)} this is defined as
 ## @tex
-## $$L = {1 \over 4} \left( {d^2 \over dx^2} M(x,y) + {d^2 \over dy^2} M(x,y) \right)$$
+## $$L = {1 \over 4} \left( \frac{\partial^2 M}{\partial{x}^2} + \frac{\partial^2 M}{\partial{y}^2} \right)$$
 ## @end tex
 ## @ifnottex
 ##

scripts/general/divergence.m

@@ -32,8 +32,9 @@
 ## @var{fy}, and @var{fz} or @var{fx}, @var{fy} respectively.
 ## @tex
 ## $$
-## div F(x,y,z) = \partial_x{F} + \partial_y{F} + \partial_z{F}
+## {\rm div \ {\bf F}}(x,y,z) \equiv \nabla \cdot {\rm \bf F} = \frac{\partial F_x}{\partial x} + \frac{\partial F_y}{\partial y} + \frac{\partial F_z}{\partial z}
 ## $$
+##
 ## @end tex
 ## @ifnottex
 ##

scripts/general/gradient.m

@@ -27,43 +27,75 @@
 ## @deftypefn  {} {@var{dx} =} gradient (@var{m})
 ## @deftypefnx {} {[@var{dx}, @var{dy}, @var{dz}, @dots{}] =} gradient (@var{m})
 ## @deftypefnx {} {[@dots{}] =} gradient (@var{m}, @var{s})
-## @deftypefnx {} {[@dots{}] =} gradient (@var{m}, @var{x}, @var{y}, @var{z}, @dots{})
+## @deftypefnx {} {[@dots{}] =} gradient (@var{m}, @var{sx}, @var{sy}, @var{sz}, @dots{})
 ## @deftypefnx {} {[@dots{}] =} gradient (@var{f}, @var{x0})
 ## @deftypefnx {} {[@dots{}] =} gradient (@var{f}, @var{x0}, @var{s})
-## @deftypefnx {} {[@dots{}] =} gradient (@var{f}, @var{x0}, @var{x}, @var{y}, @dots{})
+## @deftypefnx {} {[@dots{}] =} gradient (@var{f}, @var{x0}, @var{sx}, @var{sy}, @dots{})
 ##
 ## Calculate the gradient of sampled data or a function.
+## @tex
+## $$
+## {\rm grad} \ F(x,y,z) \equiv \nabla F = \frac{\partial F_x}{\partial x} \hat{i} + \frac{\partial F_y}{\partial y} \hat{j} + \frac{\partial F_z}{\partial z} \hat{k}
+## $$
+## @end tex
+## @ifnottex
 ##
-## If @var{m} is a vector, calculate the one-dimensional gradient of @var{m}.
-## If @var{m} is a matrix the gradient is calculated for each dimension.
+## @group
+## @verbatim
+##                   d                d                 d
+## grad F(x,y,z)  =  -- F(x,y,z) i  + -- F(x,y,z) j  +  -- F(x,y,z) k
+##                   dx               dy                dz
+## @end verbatim
+## @end group
 ##
-## @code{[@var{dx}, @var{dy}] = gradient (@var{m})} calculates the
-## one-dimensional gradient for @var{x} and @var{y} direction if @var{m} is a
-## matrix.  Additional return arguments can be use for multi-dimensional
-## matrices.
+## @end ifnottex
 ##
-## A constant spacing between two points can be provided by the @var{s}
-## parameter.  If @var{s} is a scalar, it is assumed to be the spacing for all
-## dimensions.  Otherwise, separate values of the spacing can be supplied by
-## the @var{x}, @dots{} arguments.  Scalar values specify an equidistant
-## spacing.  Vector values for the @var{x}, @dots{} arguments specify the
-## coordinate for that dimension.  The length must match their respective
-## dimension of @var{m}.
+## If @var{m} is a vector, calculate the one-dimensional numerical gradient of
+## @var{m}.  If @var{m} is a matrix the gradient is calculated for each
+## dimension.  The return argument(s) are the estimated partial derivatives
+## for each dimension at the specified sample points.
 ##
-## At boundary points a linear extrapolation is applied.  Interior points
-## are calculated with the first approximation of the numerical gradient
+## The default spacing of between data points is 1.  A constant spacing between
+## points can be specified with the @var{s} parameter.  If @var{s} is a scalar,
+## the single spacing value is used for all dimensions.  Otherwise, separate
+## values of the spacing can be supplied by the @var{sx}, @dots{} arguments.
+## Scalar values specify an equidistant spacing.  Vector values for the
+## @var{sx}, @dots{} arguments specify the coordinate for that dimension.  The
+## length must match the respective dimension of @var{m}.
+##
+## If the first argument @var{f} is a function handle, the gradient of the
+## function is calculated for the points in @var{x0}.  As with sampled data,
+## the spacing values between the points from which the gradient is estimated
+## can be set via the @var{s} or @var{dx}, @var{dy}, @dots{} arguments.  By
+## default a spacing of 1 is used, however this is normally overly large unless
+## the function is very slowly varying, and it is often necessary to specify a
+## smaller sample spacing.
+##
+## Example: numerical gradient of @code{cos} (analytically = @code{-sin})
 ##
 ## @example
-## y'(i) = 1/(x(i+1)-x(i-1)) * (y(i-1)-y(i+1)).
+## @group
+## gradient (@@cos, pi/2, .1)
+## @result{} -0.9983
+## -sin (pi/2)
+## @result{} -1
+## @end group
+## @end example
+##
+## Programming Notes:
+## The value for interior data points is approximated using the central
+## difference.
+##
+## @example
+## y'(i) = 1/2 * (y(i+1) - y(i-1)).
+## @end example
+##
+## At boundary points a linear extrapolation is applied.
+##
+## @example
+## y'(1) = y(2) - y(1).
 ## @end example
 ##
-## If the first argument @var{f} is a function handle, the gradient of the
-## function at the points in @var{x0} is approximated using central difference.
-## For example, @code{gradient (@@cos, 0)} approximates the gradient of the
-## cosine function in the point @math{x0 = 0}.  As with sampled data, the
-## spacing values between the points from which the gradient is estimated can
-## be set via the @var{s} or @var{dx}, @var{dy}, @dots{} arguments.  By default
-## a spacing of 1 is used.
 ## @seealso{diff, del2}
 ## @end deftypefn