What Is \box255 in TeX?
At a glance
- 1. Read the syntax
The primitive \box retrieves a box register; 255 is the register number.
- 2. Check the context
During page output, TeX conventionally places the completed page in box register 255.
- 3. Know what it does
\box255 removes the box from its register and inserts it where the command is used.
- 4. Ship the page
An output routine commonly uses \shipout\box255 to send the page to the output.
In TeX, \box255 means “take the box stored in register 255 and insert it here.” The number 255 is not part of a special command name: \box is the primitive, and 255 identifies the register it acts on.
Register 255 has a conventional role in page building. When TeX calls an output routine, it places the page being processed in box register 255. That is why you often see \shipout\box255 in explanations of TeX output routines: it sends that page to the output device.
What the \box primitive does
TeX box registers hold typeset material, such as a horizontal box (\hbox) or a vertical box (\vbox). The command \box<number> retrieves the box from the numbered register and puts it into the current list. Retrieving it this way empties the register. If you want to insert the contents while keeping the stored box, use \copy<number> instead.
For example, this document puts the same stored box into the text twice, first using \copy and then using \box:
\documentclass{article}
\newbox\demo
\begin{document}
\setbox\demo=\hbox{A boxed letter}
\copy\demo\quad % The register still contains the box.
\box\demo % Inserts it and empties the register.
\ifvoid\demo
\typeout{The demo box register is now void.}
\fi
\end{document}
Here \newbox\demo allocates a box register and \setbox stores material in it. After \box\demo, the test \ifvoid\demo succeeds because the register has been emptied. The example uses a named register so it does not interfere with register 255.
Why register 255 matters
TeX’s page builder collects material for a page. When it decides that a page is ready for output, it calls the output routine with the page in register 255. A basic output routine can ship the page with:
\shipout\box255
The \box255 part retrieves and empties the page box; \shipout sends that box out. Real output routines can do more, such as add headers and footers, arrange multiple columns, or defer a page. The key point is that the routine receives the page in this designated box register.
LaTeX builds on TeX’s output mechanism and may use internal names or additional steps rather than displaying this exact line in the code you normally write. The convention still explains why register 255 appears in low-level TeX discussions of page output.
What if you use \box255 elsewhere?
Outside an output routine, it still means exactly the same thing: retrieve box register 255. It does not automatically mean “the current page.” If the register is empty, the command has no stored box material to insert. If some code has put other material there, that material is what \box255 retrieves.
For that reason, ordinary document code should generally allocate a box with \newbox and use its assigned name. Register 255 is conventionally used by the output routine, so taking it over can disrupt page output or conflict with packages and macros.
Common mistakes
- Treating
\box255as a single named macro. It is the\boxprimitive followed by register number 255. - Assuming it always contains a page. That is the output-routine convention; outside that context, register 255 may be empty or hold something else.
- Using
\boxwhen you meant\copy.\boxempties the register after retrieval. Use\copyto leave the stored box available. - Using register 255 for your own document material. Allocate a register with
\newboxinstead, so you do not collide with output-routine code.
References
- The TeXbook, Donald E. Knuth
- TeX by Topic: A TeXnician’s Reference, Victor Eijkhout
Spotted an error? Send a correction. Read how we write and check articles in our editorial policy.