What tips and tricks are there for debugging TikZ/PGF code?

When answering questions here and when drawing my own complicated TikZ/PGF drawings, I've developed a fair number of "tips and tricks" for debugging the code. I'm sure that others have as well. I think it would be useful to accumulate a list of such, whence this question:

What are your tips and tricks for debugging TikZ/PGF code?

Note: in one sense this seems an obvious candidate for making Community Wiki as there is no single answer. However, I think that these tricks take some ingenuity and so deserve to gain their authors a modicum of reputation, whence I'm reluctant to make it a CW question (of course, I'll donate all my reputation gained from this question to a worthy cause). Once there are a fair few answers, I can see that organising them into a single CW answer would be a good thing, but that doesn't mean that the question should be CW. On the other hand, whilst in favour of it not being CW, I wouldn't be in anyway upset if the feeling was that it should be CW.

-
In addition to your concerns, I would like to ask if usage of QTikZ counts as a tip. It is an indispensable tool for me to see where the error is but still, one might consider that this is not a tip or trick. – percusse Sep 28 '11 at 10:07
@percusse: I guess you’re using QTikZ with Linus, but do you know how I can build it for OS X? – Tobi Sep 28 '11 at 10:56
@Tobi You can see the comments here which discusses Mac OSX case extensively. – percusse Sep 28 '11 at 11:03
@percusse: Thanks but it doen’t work. I don’t know why I guess I’m to stupid for install an app via Terminal. It’s always the same: I do exactly what the install guide say but it doesn’t work :-( (ps. Sorry Andrew for misusing your question …) – Tobi Sep 28 '11 at 16:59
I have noticed in the past that TikZ/PGF is quite forgiving, unlike regular LaTeX, in the sense that adding non-existent or incorrectly located options/keywords, and sometimes syntax that is a bit wonky (sorry, vague) does not result in errors. Instead, TikZ/PGF just ignores the error(s). I was wondering if there was some way to make such mistakes more explicit. In other words, make the parsing more "strict". – Faheem Mitha Sep 29 '11 at 8:51

I'll start off with the show node name key. This is very useful when trying to work out why a complicated node name isn't working (often because a period has snuck in uninvited).

Here's the code:

\makeatletter
\tikzset{%
show node name/.code={%
\expandafter\def\expandafter\tikz@mode\expandafter{\tikz@mode\show\tikz@fig@name}%
}
}
\makeatother


We add the \show code to the \tikz@mode macro to ensure that the node name is set by the time we're called. Otherwise \node[show node name] (hello) {}; wouldn't work.

-

Sometimes, one gets an error message without its context (like "could not read this number") -- and one wonders why and where.

What I do in this case is to add

\tracingmacros=2 \tracingcommands=2


somewhere before the offending position. This can easily produce hundreds of megabytes of .log files - but it will surely identify the position because it is a kind of "disassambly" of TeX.

As any other kind of disassembly it is hard to read. But if one aborts latex at its first error, one can scroll through the huge log file until one finds keywords which look familiar (in case of a wrong number, one may find the number parsing routine and its argument).

-
Note that a related way is to insert \message{<text>^^J} somewhere into your sources (or perhaps into tikz.code.tex ;-) ). The ^^J causes a line break. – Christian Feuersänger Sep 28 '11 at 21:24

Label Coordinates:

I posted this as part of an answer on How to draw a cube with TikZ where all faces have a distinct color?, and while it is rather obvious, and I still use it, I feel that it might help new users.

At the end of a picture I add a \foreach loop to label all the important nodes so that I can see where they are:

%% Following is for debugging purposes so you can see where the points are
%% These are last so that they show up on top
\foreach \xy in {O, A, B, C, D, E, F, G}{
\node at (\xy) {\xy};
}


This does require some discipline in not using coordinates without labeling them. I never delete this code, but just comment it out as you never know when you have to come back and make tweaks.

-

When working with clips, it can be useful to actually render the paths to see if the path is what you expect it to be. When doing this, use \fill and not \draw. The reason is that clipped paths have to be closed so PGF will automatically close any unclosed path and this may introduce unexpected behaviour. As \fill has the same behaviour, it is thus better for debugging than \draw. As an extra, put an opacity=.5 (or similar) to get the effect of seeing through (particularly useful for combining clips).

(This was actually the direct motivation for this question.)

-

Use Different Colors for Lines

If I have copied the code from examples on this site, or in the case where the coordinates are not easy to label, then I change the line colors to make it easy to see which line part of the code produces which portion of the diagram.

Here is a snippet of code from a recent posting here that I was trying to understand:

\begin{tikzpicture}[scale=5,line width=2mm]
\draw [green](0,0,0) -- (1,0,0) -- (1,1,0) -- (0,1,0) -- cycle;
\draw [blue](1,0,0) -- (1,0,-1) -- (1,1,-1) -- (1,1,0) -- cycle;
\draw [red](0,1,0) -- (0,1,-1) -- (1,1,-1) -- (1,1,0) -- cycle;
\end{tikzpicture}


In this specific case it is not too hard to track the coordinates to see which line is which, but I find this extremely helpful in more complex cases.

-