If you ever had the need to debug a macro expansion you had to discover, that
your tools provide only little or no support for this task. For this reason
the Wave library has a tracing facility, which allows to get selectively
some information about the expansion of a certain macro or several macros.

The tracing of macro expansions generates a possibly huge amount of information,
so it is recommended, that you explicitely enable/disable the tracing for the
macro in question only. This may be done with the help of a special, Wave
specific #pragma:

This way you have the possibility to enable the tracing during the expansion
of a part of a macro only. In the sample shown there is traced the expansion
of the macro argument 'x' only. Note, that the operator _Pragma()
directives expand to nothing inside the macro expansion result.

To see, what the Wave driver generates while expanding a simple macro,
let's have a look at the tracing output for the following example:

The generated trace output is very verbose, but allows to follow every step
of the actual macro expansion process. The first line in this tracing example
contains the reference to the position, from where the macro expansion was initiated.
Additionally the following information is contained for every single macro expansion:

The reference to the position (line and column numbers), where the macro to expand was defined first
(see lines 2, 9, 21 and 32).

The real parameters supplied for this macro expansion (see lines 3, 10 and
33), this information is traced inside the invoked with block, where
the corresponding formal and actual parameters are listed.

The expansion of the given arguments (if any and if these are defined as
macros). This repeats the full tracing information for the argument macro
expansion, only indended by one level. Note though, that the macro expansion
of the actual arguments is traced, regardless of the fact, whether this argument
is really to be inserted into the replacement list after its expansion
or as it was initially supplied (see C++ Standard [16.3.1.1]: "A parameter
in the replacement list, unless preceded by a # or ## preprocessing
token or followed by a ## preprocessing token, is replaced by the
corresponding argument after all macros contained therein have been expanded"
[1]).

The result of the argument substitution (see lines 15, 23, 29 and 39), i.e.
the substituted replacement list.

The rescanning process, which again includes the full subsequent macro expansion
process of all found macros (see C++ Standard [16.3.4.1]: "After all
parameters in the replacement list have been substituted, the resulting preprocessing
token sequence is rescanned with all subsequent preprocessing tokens of the
source file for more macro names to replace." [1]).

The result of the actual macro expansion (this is the last line inside the
corresponding rescanning block - see lines 18, 26, 42 and 45).

Every found macro to expand will add an additional indentation level inside
the trace output.