How to save a box to a file so it can be viewed later for debugging purposes?

I'm trying to analyze complicated TeX code that I did not write. The code creates many boxes, some of which are nested inside others. How can I save a certain (nested) box to a file, so I can view it at my leisure after the original document has finished typesetting in order to see what this box looked like just after creation?

The saved file should be ideally an image file: jpg, png or pdf, but I'm also fine with a TeX document or a fragment thereof that I can complete to a working document and typeset normally.

• \shipout\mybox would make a page that just contains that box, is that what you mean?, although more useful for debugging is \showbox\mybox which puts a representation of the box in the log. – David Carlisle Aug 5 '17 at 10:33
• @DavidCarlisle: Thanks. Both methods sound very helpful and they complement each other. But what will the shipout page be named? And won't it interfere with the normal processing and typesetting of the original document? – Evan Aad Aug 5 '17 at 10:36

TeX provides \showbox. The amount of information can be configured by \showboxbreadth and \showboxdepth. TeX stops like an error message, but writes the contents of the box to the .log file. Example:

\showboxbreadth=2147483647 % largest number
\showboxdepth=2147483647 % largest number
\tracingonline=1 % optional to show output to the console additionally

\setbox0=\hbox{Hello World}
\showbox0

\csname @@end\endcsname\end


Result:

> \box0=
\hbox(6.94444+0.0)x52.52788
.\tenrm H
.\tenrm e
.\tenrm l
.\tenrm l
.\tenrm o
.\glue 3.33333 plus 1.66666 minus 1.11111
.\tenrm W
.\kern-0.83334
.\tenrm o
.\tenrm r
.\tenrm l
.\tenrm d

! OK.
l.6 \showbox0


There is also \showlists that outputs the current main vertical list.

\documentclass{article}
\showboxdepth=\maxdimen
\tracingonline=1
\begin{document}
$E=mc^2$

\showlists
\end{document}


Result:

### vertical mode entered at line 0
### current page:
\write-{}
\glue(\topskip) 10.0
\hbox(0.0+0.0)x345.0, glue set 122.9979fil
.\hbox(0.0+0.0)x15.0
.\hbox(0.0+0.0)x207.0021, glue set 103.50105fil
..\glue 0.0 plus 1.0fil minus 1.0fil
..\glue 0.0 plus 1.0fil minus 1.0fil
.\penalty 10000
.\glue(\parfillskip) 0.0 plus 1.0fil
.\glue(\rightskip) 0.0
\penalty 10000
\glue(\abovedisplayskip) 10.0 plus 2.0 minus 5.0
\glue(\baselineskip) 3.35997
\hbox(8.64003+0.0)x38.88536, shifted 153.05733, display
.\OML/cmm/m/it/10 E
.\kern0.57637
.\glue(\thickmuskip) 2.77771 plus 2.77771
.\OT1/cmr/m/n/10 =
.\glue(\thickmuskip) 2.77771 plus 2.77771
.\OML/cmm/m/it/10 m
.\OML/cmm/m/it/10 c
.\hbox(4.51111+0.0)x4.48613, shifted -4.12892
..\OT1/cmr/m/n/7 2
\penalty 0
\glue(\belowdisplayskip) 10.0 plus 2.0 minus 5.0
total height 42.0 plus 4.0 minus 10.0
goal height 550.0
prevdepth 0.0, prevgraf 4 lines

! OK.
l.8 \showlists


\shipout

A box can be output with \shipout. The .log file contains the page numbers in square brackets. Usually, it's only the counter page with register number 0. But, TeX supports all count registers from 0 to 9. The example uses count register 1 with value 42:

\documentclass[a5paper]{article}
\usepackage{lipsum}
\begin{document}
\lipsum
\sbox0{Hello World}
\begingroup
\count1=42 % local change inside the group
\shipout\copy0 % copy the box to output and keep contents
\endgroup
\lipsum
\end{document}


The console output contains:

[1] [2] [3.42] [3] [4] [5] [6]


There are seven pages. The third page, marked with 3.42 contains the box.

Of course, you are free to output something more descriptive:

\shipout\vbox{\hbox{My name}\noindent\fbox{\copy0}}%


or

\documentclass[a5paper]{article}
\usepackage{lipsum}
\begin{document}
\lipsum
\sbox0{Hello World}
\begingroup
\count1=42 %
\shipout\hbox{%
\begin{tabular}{ll}
\multicolumn{2}{c}{\textbf{Box output}}\\
Width: & \the\wd0 \\
Height: & \the\ht0 \\
Depth: & \the\dp0 \\
\multicolumn{2}{c}{\fbox{\copy0}}%
\end{tabular}%
}%
\endgroup
\lipsum
\end{document}


• Thanks. What if I want to view the box, to be able to determine at the flick of the eye, say, what color was used to stroke the bounding box? – Evan Aad Aug 5 '17 at 10:42
• @EvanAad This is already answered in David Carlisle's comment (\shipout). – Heiko Oberdiek Aug 5 '17 at 10:45
• What will the shipout page be named? And will it interfere with the normal processing and typesetting of the original document? – Evan Aad Aug 5 '17 at 10:47
• Is the \csname @@end\endcsname\end in your first example necessary? What's its purpose? – Evan Aad Aug 5 '17 at 11:45
• @EvanAad This ends the TeX or LaTeX file. The example can be processed with both plain TeX and LaTeX. – Heiko Oberdiek Aug 5 '17 at 12:25