% output=pdftex engine=pdftex language=uk
%
% copyright=pragma-ade readme=readme.pdf licence=cc-by-nc-sa

\startcomponent mfun-014

\environment mfun-000

\chapter [sec:debugging] {Debugging}

\startintro

Those familiar with \CONTEXT\ will know that it has quite
some visual debugging features build in. So, what may you
expect of the \METAPOST\ macros that come with \CONTEXT ? In
this chapter we will introduce a few commands that show some
insight in what \METAPOST\ is doing to your paths.

\stopintro

Since the outcome of \METAPOST\ code is in many respects
more predictable than that of \TEX\ code, we don't need that
advanced visual debugging features. Nevertheless we provide
a few, that are all based on visualizing paths.

\startbuffer
path p ; p := fullcircle scaled 4cm ;
drawpath p ; drawpoints p ; drawpointlabels p ;
\stopbuffer

\startlinecorrection[blank]
\processMPbuffer
\stoplinecorrection

This visualization is achieved by using dedicated drawing
commands:

\typebuffer

Since control points play an important role in defining the
shape, visualizing them may shed some insight in what
\METAPOST\ is doing.

\startbuffer
path p ; p := fullcircle xscaled 4cm yscaled 3cm ;
drawpath p ; drawcontrollines p ;
drawpoints p ; drawcontrolpoints p ; drawpointlabels p ;
\stopbuffer

\typebuffer

The pre and post control points show up as small dots and are
connected to their parent point with thin lines.

\startlinecorrection[blank]
\processMPbuffer
\stoplinecorrection

You can deduce the direction of a path from the way the
points are numbered, but using an arrow to indicate the
direction is more clear.

\startbuffer
path p ; p := fullcircle xscaled 4cm yscaled 3cm ;
drawarrowpath p ; drawcontrollines p ;
drawpoints p ; drawcontrolpoints p ; drawpointlabels p ;
\stopbuffer

\typebuffer

The \type {drawarrowpath} is responsible for the arrow.
Especially when you are in the process of defining macros
that have to calculate intersections or take subpaths,
knowing the direction may be of help.

\startlinecorrection[blank]
\processMPbuffer
\stoplinecorrection

The next table summarizes the special drawing commands:

\starttabulate[|lT|l|]
\HL
\NC drawpath           \NC the path                         \NC \NR
\NC drawarrowpath      \NC the direction of the path        \NC \NR
\NC drawcontrollines   \NC the lines to the control points  \NC \NR
\NC drawpoints         \NC the points that make up the path \NC \NR
\NC drawcontrolpoints  \NC the control points of the points \NC \NR
\NC drawpointlabels    \NC the numbers of the points        \NC \NR
\HL
\stoptabulate

You can set the characteristics of these like you set \type
{drawoptions}. The default settings are as follows:

\starttyping
drawpathoptions   (withpen pencircle scaled 5   withcolor .8white) ;
drawpointoptions  (withpen pencircle scaled 4   withcolor   black) ;
drawcontroloptions(withpen pencircle scaled 2.5 withcolor   black) ;
drawlineoptions   (withpen pencircle scaled 1   withcolor .5white) ;
drawlabeloptions  () ;
\stoptyping

Two more options are \type {draworiginoptions} and \type
{drawboundoptions} which are used when visualizing the
bounding box and origin.

\startbuffer
swappointlabels  := true ;
path p ; p := fullcircle xscaled 4cm yscaled 3cm ;
drawarrowpath p ; drawcontrollines p ;
drawpoints p ; drawcontrolpoints p ; drawpointlabels p ;
drawboundingbox p ; draworigin ;
\stopbuffer

\typebuffer

In this example we have set \type {swappointlabels} to change
the place of the labels. You can set the variable \type
{originlength} to tune the appearance of the origin.

\startlinecorrection[blank]
\processMPbuffer
\stoplinecorrection

You can pass options directly, like you do with \type {draw}
and \type {fill}. Those options override the defaults.

\startbuffer
path p ; p := fullcircle xscaled 6cm yscaled 3cm rotated 15 ;
drawarrowpath     p ;
drawcontrollines  p withcolor .625red ;
drawpoints        p withcolor .625yellow ;
drawcontrolpoints p withcolor .625yellow ;
drawpointlabels   p withcolor .625yellow ;
drawboundingbox   p ;
draworigin          withcolor .625red ;
\stopbuffer

\startlinecorrection[blank]
\processMPbuffer
\stoplinecorrection

Here we used the options:

\typebuffer

Sometimes it makes sense to draw a simple coordinate system,
and for that purpose we have three more macros. They draw
axis and tickmarks.

\startbuffer
drawticks unitsquare xscaled 4cm yscaled 3cm shifted (-1cm,-1cm) ;
\stopbuffer

\typebuffer

The system drawn is based on the bounding box specification
of the path passed to the macro. You can also draw one axis,
using \type {drawxticks} or \type {drawyticks}. Here we show
the previous command.

\startlinecorrection[blank]
\processMPbuffer
\stoplinecorrection

By default, the ticks are placed at .5cm distance, but you
can change this by setting \type {tickstep} to a different
value.

\startbuffer
tickstep := 1cm ; ticklength := 2mm ;
drawticks fullsquare xscaled 4cm yscaled 3cm ;
tickstep := tickstep/2 ; ticklength := ticklength/2 ;
drawticks fullsquare xscaled 4cm yscaled 3cm ;
\stopbuffer

\typebuffer

The \type {ticklength} variable specifies the length of a
tick. Here we manipulated both the variables to get a more
advanced system.

\startlinecorrection[blank]
\processMPbuffer
\stoplinecorrection

If visualizing a path would mean that we would have to key
in al those draw||commands, you could hardly call it a
comfortable tool. Therefore, we can say:

\startbuffer
drawwholepath fullsquare scaled 3cm rotated 30 randomized 5mm ;
\stopbuffer

\typebuffer

The \type {drawwholepath} command shows everything except the
axis.

\startlinecorrection[blank]
\processMPbuffer
\stoplinecorrection

If even this is too much labour, you may say:

\starttyping
visualizepaths ;
\stoptyping

This redefines the \type {draw} and \type {fill} command in
such a way that they also show all the information.

\startbuffer
visualizepaths ;
draw fullsquare scaled 3cm rotated 30 randomized 2mm ;
\stopbuffer

\typebuffer

You may compare this feature to the \type {\showmakeup}
command available in \CONTEXT, that redefines the \TEX\
primitives that deal with boxes, glues, penalties, and
alike.

\startlinecorrection[blank]
\processMPbuffer
\stoplinecorrection

Of course you may want to take a look at the \METAPOST\
manual for its built in (more verbose) tracing options. One
command that may prove to be useful is \type {show}, that you
can apply to any variable. This command reports the current
value (if known) to the terminal and log file.

\startlinecorrection[blank]
{\showmakeup\processMPbuffer}
\stoplinecorrection

The previous picture shows what is typeset when we also say
\type {\showmakeup}. This command visualizes \TEX's boxes,
skips, kerns and penalties. As you can see, there are some
boxes involved, which is due to the conversion of \METAPOST\
output to \PDF.

\starttyping
\startlinecorrection[blank]
... the graphic ...
\stoplinecorrection
\stoptyping

The small bar is a kern and the small rectangles are
penalties. More details on this debugger can be found in the
\CONTEXT\ manuals and the documentation of the modules
involved.

\stopcomponent
