% trace.tex copyright 1992 Victor Eijkhout
%                 copyright 2014--2016 Vafa Khalighi
%
%
%    This program is free software: you can redistribute it and/or modify
%    it under the terms of the GNU General Public License as published by
%    the Free Software Foundation, either version 3 of the License, or
%    (at your option) any later version.
%
%    This program is distributed in the hope that it will be useful,
%    but WITHOUT ANY WARRANTY; without even the implied warranty of
%    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
%    GNU General Public License for more details.
%
%    You should have received a copy of the GNU General Public License
%    along with this program.  If not, see <http://www.gnu.org/licenses/>.
%
%
\Chapter[chap:tracing] Tracing

\Section Do you really want to see this?

You can get glimpses of Lollipop's internal workings by enabling some
of the internal traces. The extreme positions
\Ver>    \Trace:yes<Rev
and
\Ver>    \Trace:no<Rev
cause all trace information and no trace at all respectively to be
generated. You may find this trace interesting, or it may dumbfound you.
Of course, if your name is Victor you find it pretty useful.

The following traces are available:
\Ver>    \NewTrace:def  % definition of user constructs
    \NewTrace:ref  % cross references
    \NewTrace:ext  % external files
    \NewTrace:doc  % document structure
    \NewTrace:font % font loading
    \NewTrace:out  % output routine
    \NewTrace:indent % indentation control
    \NewTrace:gen  % general tools<Rev

\ImpNote
Trace messages are generated by calls to
\Ver>    \Tmessage[type]{text}<Rev
Setting
\Ver>    \Trace:no<Rev
defines \cs{Tmessage} to discard its arguments. This is the most
efficient way of generating no trace information.

Tracing is controlled by a global parameter \cs{trace@all}. 
A value of~$-1$
disables all tracing; $+1$~corresponds to all tracing on; $0$~gives
selective tracing. In the third case a call
\Ver>    \Trace:xyz<Rev
set \ver>\trace:xyz> positive so that only 
\ver>\Tmessage[xyz]{...}> calls will
produce output. Enabling a selective trace sets \cs{trace@all} to zero, in
case it was~$-1$.
\ImpNoteStop

\endinput