% -*- texinfo -*-
% @deftypefn {Function File} {@var{l} =} legendre (@var{n}, @var{x})
% @deftypefnx {Function File} {@var{l} =} legendre (@var{n}, @var{x}, @var{normalization})
% Compute the Legendre function of degree @var{n} and order
% @var{m} = 0 @dots{} N. The optional argument, @var{normalization},
% may be one of @code{'unnorm'}, @code{'sch'}, or @code{'norm'}.
% The default is @code{'unnorm'}. The value of @var{n} must be a
% non-negative scalar integer.
%
% If the optional argument @var{normalization} is missing or is
% @code{'unnorm'}, compute the Legendre function of degree @var{n} and
% order @var{m} and return all values for @var{m} = 0 @dots{} @var{n}.
% The return value has one dimension more than @var{x}.
%
% The Legendre Function of degree @var{n} and order @var{m}:
%
% @example
% @group
% m m 2 m/2 d^m
% P(x) = (-1) * (1-x ) * ---- P (x)
% n dx^m n
% @end group
% @end example
%
% @noindent
% with Legendre polynomial of degree @var{n}:
%
% @example
% @group
% 1 d^n 2 n
% P (x) = ------ [----(x - 1) ]
% n 2^n n~ dx^n
% @end group
% @end example
%
% @noindent
% @code{legendre (3, [-1.0, -0.9, -0.8])} returns the matrix:
%
% @example
% @group
% x | -1.0 | -0.9 | -0.8
% ------------------------------------
% m=0 | -1.00000 | -0.47250 | -0.08000
% m=1 | 0.00000 | -1.99420 | -1.98000
% m=2 | 0.00000 | -2.56500 | -4.32000
% m=3 | 0.00000 | -1.24229 | -3.24000
% @end group
% @end example
%
% If the optional argument @code{normalization} is @code{'sch'},
% compute the Schmidt semi-normalized associated Legendre function.
% The Schmidt semi-normalized associated Legendre function is related
% to the unnormalized Legendre functions by the following:
%
% For Legendre functions of degree n and order 0:
%
% @example
% @group
% 0 0
% SP (x) = P (x)
% n n
% @end group
% @end example
%
% For Legendre functions of degree n and order m:
%
% @example
% @group
% m m m 2(n-m)~ 0.5
% SP (x) = P (x) * (-1) * [-------]
% n n (n+m)~
% @end group
% @end example
%
% If the optional argument @var{normalization} is @code{'norm'},
% compute the fully normalized associated Legendre function.
% The fully normalized associated Legendre function is related
% to the unnormalized Legendre functions by the following:
%
% For Legendre functions of degree @var{n} and order @var{m}
%
% @example
% @group
% m m m (n+0.5)(n-m)~ 0.5
% NP (x) = P (x) * (-1) * [-------------]
% n n (n+m)~
% @end group
% @end example
% @end deftypefn