TeX Boxes

From Wiki
Jump to navigation Jump to search

Boxes are the basis of all (low level) TeX typesetting. As the building blocks they store typeset parts of lines, paragraphs or pages. For storing material not being typeset yet, like input text for later use, use Buffers.

The introduction to LuaTeX boxes can be found in Pandora’s \hbox: Using LuaTeX to Lift the Lid of TeX Boxes.

LuaMetaTeX boxes serve the same purpose, but their properties are changed and extended. For the details see Low Level TeX: Boxes manual.

Cached Boxes (LMTX)

Box has to be typeset with TeX. Usually the user is on the TeX side, where box is typeset, stored and can be used later. However, combining TeX with Lua demands some extra work. While being on the Lua side to typeset and store the box you must finish the Lua block jump to TeX and typeset boxes. Thus setting the boxes on Lua side will be forgotten and boxes will not exist after finishing the Lua block. To let TeX do something from within Lua there is a Lua Steps mechanism described in CLD Manual, but in LMTX we also have mechanism for cached boxes.

List of the commands to work with cached boxes:

\putboxincache          {category} {name} number
\getboxfromcache        {category} {name} number
\doifelseboxincache     {category} {name}
\copyboxfromcache       {category} {name} number
\directboxfromcache     {category} {name}
\directcopyboxfromcache {category} {name}
\resetboxesincache      {category}
\putnextboxincache      {category} {name} box
\getboxwdfromcache      {category} {name}
\getboxhtfromcache      {category} {name}
\getboxdpfromcache      {category} {name}

All these commands can be used on Lua side with the usual syntax context.<command>(<params>)

Boxed are stored in user defined categories (namespaces) and every box has its unique name inside the category.

If the boxes are not to be cached for the subsequent runs, one needs to clear the category cache at the beginning of the document.


One defines and typesets the box as usual:

                      align={flushleft}]{framed text}}

To cache that box the user can use either

\putboxincache{category}{name} 0% space is optional 



and the box can be retrieved any time later (or even in subsequent runs) with

\getboxfromcache{category}{name}% analogy to \box0, box will be forgotten


\copyboxfromcache{category}{name}% analogy to \copy0, box will persist


One can trace the creation of cached boxes in log or console with


To visualize boxes (hbox, vbox) in PDF use


Tracing in general is explained in Debugging.