138
edits
Changes
Jump to navigation
Jump to search
New page on TeX boxes
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_in_LuaTeX|Buffers]].
The introduction to LuaTeX boxes can be found in [https://www.overleaf.com/learn/latex/Articles/Pandora%E2%80%99s_%5Chbox:_Using_LuaTeX_to_Lift_the_Lid_of_TeX_Boxes|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 [http://distribution.contextgarden.net/current/context/latest/doc/context/documents/general/manuals/lowlevel-boxes.pdf 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 [http://distribution.contextgarden.net/current/context/latest/doc/context/documents/general/manuals/cld-mkiv.pdf CLD Manual], but in LMTX we also have mechanism for '''cached boxes'''.
List of the commands to work with cached boxes:
<texcode>
\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}
</texcode>
All these commands can be used on Lua side with the usual syntax <tt>context.<command>(<params>)</tt>
Boxed are stored in user defined '''categories''' (namespaces) and every box has its '''name''' inside its category.
If the boxes are not cached for the subsequent runs, one needs to clear the category cache at the beginning of the document.
<texcode>
\resetboxesincache{category}
</texcode>
One defines and typesets the box as usual:
<texcode>
\setbox0=\hbox{\framed[width=50mm,
background=color,
backgroundcolor=gray,
frame=off,
align={flushleft}]{framed text}}
</texcode>
To cache that box the user can use either
<texcode>
\putboxincache ... [to test]
</texcode>
or
<texcode>
\putnextboxincache{category}{name}\box0
</texcode>
and the box can be retrieved any time later (or even in subsequent runs) with
<texcode>
\getboxfromcache{category}{name}% analogy to \box0, box will be forgotten
</texcode>
or
<texcode>
\copyboxfromcache{category}{name}% analogy to \copy0, box will persist
</texcode>
One can trace the creation of cached boxes with
<texcode>
\enabletrackers[nodes.boxes]
</texcode>
The introduction to LuaTeX boxes can be found in [https://www.overleaf.com/learn/latex/Articles/Pandora%E2%80%99s_%5Chbox:_Using_LuaTeX_to_Lift_the_Lid_of_TeX_Boxes|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 [http://distribution.contextgarden.net/current/context/latest/doc/context/documents/general/manuals/lowlevel-boxes.pdf 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 [http://distribution.contextgarden.net/current/context/latest/doc/context/documents/general/manuals/cld-mkiv.pdf CLD Manual], but in LMTX we also have mechanism for '''cached boxes'''.
List of the commands to work with cached boxes:
<texcode>
\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}
</texcode>
All these commands can be used on Lua side with the usual syntax <tt>context.<command>(<params>)</tt>
Boxed are stored in user defined '''categories''' (namespaces) and every box has its '''name''' inside its category.
If the boxes are not cached for the subsequent runs, one needs to clear the category cache at the beginning of the document.
<texcode>
\resetboxesincache{category}
</texcode>
One defines and typesets the box as usual:
<texcode>
\setbox0=\hbox{\framed[width=50mm,
background=color,
backgroundcolor=gray,
frame=off,
align={flushleft}]{framed text}}
</texcode>
To cache that box the user can use either
<texcode>
\putboxincache ... [to test]
</texcode>
or
<texcode>
\putnextboxincache{category}{name}\box0
</texcode>
and the box can be retrieved any time later (or even in subsequent runs) with
<texcode>
\getboxfromcache{category}{name}% analogy to \box0, box will be forgotten
</texcode>
or
<texcode>
\copyboxfromcache{category}{name}% analogy to \copy0, box will persist
</texcode>
One can trace the creation of cached boxes with
<texcode>
\enabletrackers[nodes.boxes]
</texcode>
