trace.c
-------

History
-------
26th October 1992  JRC  Started
23rd May 1995      JRC  Updated for multiple destinations

   This is a simplified version of various other tracing modules that have
been written at various other times.

   It provides an initialisation function trace_initialise(), which
takes the name of an operating system variable, and sets up tracing in a
way that depends on its contents as follows:

      e128.5            Econet (AUN) station 128.5
      f$.trace          File $.trace
      i136.170.128.5    Internet address 136.170.128.5
      n                 null:
      s                 Standard output (may be redirected on the
                        programme command line by '> file')
      t                 Tube (HostFS or TML)
      v                 vdu: (may be redirected by '{ > file }')

   There is also a function trace_terminate() whcih closes the trace
output, and should be called before the programme exits.

   There is only one tracing function, tracef(), which takes a
|printf|-like argument line and sends it to the destination.

   This is implemtned as a macro. If the compiling is done
with -DTRACE=1, everything workd as above. Otherwise (-DTRACE=0, or
nothing), all the calls macro-expand to nothing.

   Because you can't write a macro with a variable number of arguments,
you have to play a trick to get tracef() to work with more than one
argument: you have to use a macro _, defined as

      #define _ ,

and use _ instead of , in the argument list:

      tracef ("Window handle 0x%X, icon handle %d\n" _ w _ i);
