The debug.h include file provides a very simple yet suprisingly powerful
debugging mechanism.  The benefits provided by debug.h include:

1) conditional compilation - meaning that debug(x,y) expands to an empty
statement (;) if DEBUG_MACRO is not #defined.  This lets you leave in debug
statements in case something goes wrong at a later time (in which case
you simply #define DEBUG_MACRO once again).

2) Lets one define sets of debug statements that are turned on or off as
a group.  In the normal course of debugging a program, one adds several write
(or tell) statements in an attempt to track down an current error.  After
fixing these errors, the debug statements get deleted and its on to
tracking down the next error in the program (adding a new set of debug
statements).  The problem is that sometimes the original error comes back
(under a different set of circumstances) and gee wouldn't it be nice if that original set of debug statements was still there.  The debug.h
include file provides a convenient way to do this.  Returning to the
concept of turning sets of statements on or off as a group.  It is
also possible turn sets of sets on or off as a group.

debug(x,y) is defined to be something like:

if (x & _debug_level) write(y);

Note the use of the bitwise/and operator.  This operator is what gives
the debug macro its flexibility.  The write statement gets executed only
when one of the bits set in the integer _debug_level is also set in the
variable x (the first argument to debug(x,y)).  As an example of how this
might be used: in the early stages of debugging a program you might
set_debug_level(1) and use debug macros of the form debug(1,y).  After
a period of debugging you might feel that the debug(1,y) statements have
served their purpose.  At that point, you can change the set_debug_level
call to be set_debug_level(2).  Now, the debug(1,y) statements will no
longer cause anything to be printed.  However, debug(2,y) statements would
be printed.  Suppose that an old error crops up because of a new set of
inputs that you didn't encounter before.  If the debug(1,y) statements
would again be helpful in debugging this old error, you could
call set_debug_level(3) instead of set_debug_level(2).  This would cause
BOTH debug(1,y) and debug(2,y) statements to issue writes.  This is because
the binary representaton of three (3) contains a one (1) AND a two (2).

See /obj/debug.c and /usr/include/debug.h for a concrete example of how
this works.

--Truilkan@TMI
