% -*- texinfo -*-
% @deftypefn {Function File} {@var{p} = } bchpoly
% @deftypefnx {Function File} {@var{p} = } bchpoly (@var{n})
% @deftypefnx {Function File} {@var{p} = } bchpoly (@var{n},@var{k})
% @deftypefnx {Function File} {@var{p} = } bchpoly (@var{prim},@var{k})
% @deftypefnx {Function File} {@var{p} = } bchpoly (@var{n},@var{k},@var{prim})
% @deftypefnx {Function File} {@var{p} = } bchpoly (@var{...},@var{probe})
% @deftypefnx {Function File} {[@var{p},@var{f}] = } bchpoly (@var{...})
% @deftypefnx {Function File} {[@var{p},@var{f},@var{c}] = } bchpoly (@var{...})
% @deftypefnx {Function File} {[@var{p},@var{f},@var{c},@var{par}] = } bchpoly (@var{...})
% @deftypefnx {Function File} {[@var{p},@var{f},@var{c},@var{par},@var{t}] = } bchpoly (@var{...})
%
% Calculates the generator polynomials for a BCH coder. Called with no input
% arguments @dfn{bchpoly} returns a list of all of the valid BCH codes for
% the codeword length 7, 15, 31, 63, 127, 255 and 511. A three column matrix
% is returned with each row representing a seperate valid BCH code. The first
% column is the codeword length, the second the message length and the third
% the error correction capability of the code.
%
% Called with a single input argument, @dfn{bchpoly} returns the valid BCH
% codes for the specified codeword length @var{n}. The output format is the
% same as above.
%
% When called with two or more arguments, @dfn{bchpoly} calculates the
% generator polynomial of a particular BCH code. The generator polynomial
% is returned in @var{p} as a vector representation of a polynomial in
% GF(2). The terms of the polynomial are listed least-significant term
% first.
%
% The desired BCH code can be specified by its codeword length @var{n}
% and its message length @var{k}. Alternatively, the primitive polynomial
% over which to calculate the polynomial can be specified as @var{prim}.
% If a vector representation of the primitive polynomial is given, then
% @var{prim} can be specified as the first argument of two arguments,
% or as the third argument. However, if an integer representation of the
% primitive polynomial is used, then the primitive polynomial must be
% specified as the third argument.
%
% When called with two or more arguments, @dfn{bchpoly} can also return the
% factors @var{f} of the generator polynomial @var{p}, the cyclotomic coset
% for the Galois field over which the BCH code is calculated, the parity
% check matrix @var{par} and the error correction capability @var{t}. It
% should be noted that the parity check matrix is calculated with
% @dfn{cyclgen} and limitations in this function means that the parity
% check matrix is only available for codeword length upto 63. For
% codeword length longer than this @var{par} returns an empty matrix.
%
% With a string argument @var{probe} defined, the action of @dfn{bchpoly}
% is to calculate the error correcting capability of the BCH code defined
% by @var{n}, @var{k} and @var{prim} and return it in @var{p}. This is
% similar to a call to @dfn{bchpoly} with zero or one argument, except that
% only a single code is checked. Any string value for @var{probe} will
% force this action.
%
% In general the codeword length @var{n} can be expressed as
% @code{2^@var{m}-1}, where @var{m} is an integer. However, if
% [@var{n},@var{k}] is a valid BCH code, then a shortened BCH code of
% the form [@var{n}-@var{x},@var{k}-@var{x}] can be created with the
% same generator polynomial
%
% @end deftypefn
% @seealso{cyclpoly,encode,decode,cosets}