Exploring LuaTeX nodes and boxes with Graphviz on Windows

If you are interested to explore the inner structures of TeX boxes created in LuaTeX you can do this very conveniently using the following free resources:

  • viznodelist.lua by Patrick Gundlach. This is an excellent Lua script that generates a text file containing a graph representation of the structures and nodes inside a \vbox{...} or \hbox{...}. The file output by viznodelist.lua can be opened and displayed using GVEdit (see below).
  • GVEdit is part of the Graphviz distribution and you can download a Windows installer from the Graphviz website

Installing Graphviz should be straightforward using the MSI installer provided. To use viznodelist.lua you’ll need to put the file in the appropriate place within your texmf tree. To find the right location you may need to look into your texmf.cnf file to examine the LUAINPUTS variable – which typically looks something like this:

LUAINPUTS = .;$TEXMF/scripts/{$progname,$engine,}/{lua,}//;$TEXMF/tex/{luatex,plain,generic,}//

For example, suppose your texmf folder is located at h:\texmf then you could put viznodelist.lua in the folder h:\texmf\scripts\lua.

Here’s an ultra-minimal plain LuaTeX example:

\directlua{require("viznodelist")}
\setbox1001= \vbox{\hsize=50 mm Hello \hbox{Hello}}
\directlua{viznodelist.nodelist_visualize(1001,"h:/texmf/mybox.gv")}
\bye

The above code will parse the contents of box 1001 and output a file called mybox.gv which you can open in GVEdit to view a graph of the the node structures in box 1001. The following screenshot displays this:

GVEdit can export the graph in numerous formats including PDF, PNG etc.