function s = line_parameter_s ( p1, p2, p )

%*****************************************************************************80
%
%% LINE_PARAMETER_S returns the S parameter of a point with respect to a line.
%
%  Discussion:
%
%    If P is on the line from P1 to P2, then S represents its
%    relative distance from P1.  S will be 0 if P = P1, and
%    1 if P = P2.  It will lie between 0 and 1 if P lies between
%    P1 and P2, and so on.
%
%    If P does not lie on the line, then S will be the coordinate
%    of the point on the line that is nearest to P.
%
%    P1 and P2 must be column vectors.
%
%    P must be a column vector or an array of column vectors.
%
%    The spatial dimension is arbitrary.
%
  [ m, n ] = size ( p );

  v1 = ( p2 - p1 );
  v2 = ( p  - repmat ( p1, 1, n ) );
  s = ( v1' * v2 ) / ( v1' * v1 );

  return
end
