function [] = polpac_debugging()
%
%  POLPAC maintains a global variable DEBG with values between 0..3.  Since
%  the testing for consistency of the data can be quite extensive (and thus
%  slow), it was decided to introduce 4 levels of debugging.
%
%  Normally (and that is the default value), you want to run POLPAC at the
%  debug level zero (i.e. DEBG=0).  In this mode, very little consistency
%  testing is done, and the code executes consequently at high speed.
%
%  If an error occurs that you cannot explain, we suggest to raise the
%  debug level to one by setting DEBG=1, and rerun the code.  At that
%  level, POLPAC tests the consistency of parameter calls at the control
%  level.  Your code executes more slowly, but not very much more slowly, and
%  misunderstandings of how the control routines work can be found easily.
%
%  If this does not help yet, raise the debug level to two (DEBG=2).  At that
%  level, POLPAC tests in addition also integrity of parameter calls at the
%  level of data conversion routines.
%
%  If this does still not help, raise the debug level to three (DEBG=3).
%  Now, even data definitions are debugged.  Please, be prepared to have
%  some patience.  The code will now execute painfully slow, but this
%  should sure do it (!)
%
%  POLPAC provides for a number of different means to trace errors.
%
%   a. If an error occurred, you can use the TTRACE command to retrieve
%      the sequence of POLPAC function calls that led to the error.  Since
%      tracing is by default disabled, you may need to switch on the
%      tracing facility (TRACEON), and rerun the erroneous code to reproduce
%      the error before you can get a trace.
%
%   b. Raise the DEBG flag to whatever level needed (c.f. topic "debugging")
%      to analyze the problem in more depth.
%
%   c. If POLPAC caught an error (through its ABORT facility), the trace
%      stack will be automatically emptied after a trace was displayed, and
%      the function call nesting level (STKDEPTH) will be reset to zero.  If
%      you produced your own error which is caught either by Matlab or even
%      by C (TRAP-errors), there is no way how POLPAC can know this.
%      Therefore, the trace will not be emptied and, more troublesome, the
%      nesting level will not be reset to zero.  Thus, even if you do not use
%      the tracing facility, after a few errors only, you will no longer be
%      able to execute any POLPAC code since the system will assume that you
%      arrived at your maximum permitted function call nesting level (10).
%      Use NEWTRACE to clear the trace stack and to reset your nesting level
%      counter (STKDEPTH) to zero.
%
return
