% language=uk % % copyright=pragma-ade readme=readme.pdf licence=cc-by-nc-sa \startcomponent mfun-debugging \environment metafun-environment \startchapter[reference=sec:debugging,title={Debugging}] \index{debugging} \startintro Those familiar with \CONTEXT\ will know that it has quite some visual debugging features build in. So, what can 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. \stopintro \startsection[title=Showing paths] 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. \stopsection \startsection[title=Comments] Sometimes, when trouble strikes, you might want to peek in the \PDF\ file to see what gets written there. Each graphic is marked with a number but when you have many it might make sense to add a comment to help you locate the code. \startbuffer \startMPcode comment("test graphic") ; message("processing a test graphic") ; draw fullsquare scaled 1cm ; \stopMPcode \stopbuffer \typebuffer This renders as: \startlinecorrection[blank] \getbuffer \stoplinecorrection On the console we get these messages: \starttyping metapost > message : processing a test graphic metapost > warning : processing a test graphic \stoptyping And in the \PDF\ file we will find: \starttyping % mps graphic 1: begin % mps graphic 1: test graphic q 0 g 0 G 10 M 1 j 1 J 0.500000000 w -14.173233032 -14.173233032 m 14.173233032 -14.173233032 l 14.173233032 14.173233032 l -14.173233032 14.173233032 l -14.173233032 -14.173233032 l h S 0 g 0 G Q % mps graphic 1: end \stoptyping Here are some examples of constructed messages: \starttyping message "2: okay (done)" ; message "1: " & dq & "okay" & dq & " (done)" ; message "3: " & quotation "okay" & " (done)" ; message "3: " & quote "okay" & " (done)" ; message "4: " & quotation 123 & " (done)" ; message "5: " & quotation true & " (done)" ; message "6: " & quote true & " (done)" ; message "7: " & tostring true & " (done)" ; message "8: " & tostring (1,2) & " (done)" ; message "9: " & topair (1,2) & " (done)" ; \stoptyping and this is what you get: \starttyping metapost > message : 2: okay (done) metapost > message : 1: "okay" (done) metapost > message : 3: "okay" (done) metapost > message : 3: 'okay' (done) metapost > message : 4: "123" (done) metapost > message : 5: "true" (done) metapost > message : 6: 'true' (done) metapost > message : 7: true (done) metapost > message : 8: 1 2 (done) metapost > message : 9: (1,2) (done) \stoptyping \stopsection \startsection[title=Pens] A circular pen is applied to a path in a different way than for instance a square pen. Circular pens are mapped onto \POSTSCRIPT\ pens while for other pens an outline is calculated that gets filled. Take this code: \startbuffer[a] \startMPcode draw fullcircle xscaled 6cm yscaled 3cm withpen pensquare scaled 5mm rotated 30 withcolor .625yellow ; \stopMPcode \stopbuffer \startbuffer[b] \startMPcode draw envelope pensquare scaled 5mm rotated 30 of (fullcircle xscaled 6cm yscaled 3cm) withpen pencircle scaled 1mm withcolor .375white ; \stopMPcode \stopbuffer \startbuffer[c] \enabletrackers[metapost.forcestroke] \startMPcode draw fullcircle xscaled 6cm yscaled 3cm withpen pensquare scaled 5mm rotated 30 withcolor .625red ; \stopMPcode \disabletrackers[metapost.forcestroke] \stopbuffer \typebuffer[a] and this: \typebuffer[b] and: \typebuffer[c] When we overlay these three we get. The envelope only returns the outer curve. \startlinecorrection[blank] \startoverlay {\getbuffer[a]} {\getbuffer[b]} {\getbuffer[c]} \stopoverlay \stoplinecorrection \stopsection \stopchapter \stopcomponent