7

I've searched everywhere on this website and google for a tutorial but I don't see many, which I thought it was weird.

I've found this page https://en.wikibooks.org/wiki/LaTeX/Boxes but it still doesn't explain what the newbox command does.

Rainb
  • 217
  • Welcome! \setbox allows you to define a new box that you can set e.g. with \setbox. You can then copy it with \copy. E.g. \documentclass{article} \newbox\Rainbox \setbox\Rainbox\hbox{Rainbow} \begin{document} \copy\Rainbox \end{document. It is hard to just discuss \newbox without discussing the full concept of boxes in TeX. –  Jan 12 '20 at 22:35
  • what is then the difference between setbox and newbox? – Rainb Jan 12 '20 at 22:55
  • @Rainb \newbox allocates a new box register (much like allocating a variable in other programming languages). \setbox adds stuff to that box. – Phelype Oleinik Jan 12 '20 at 22:56
  • \setbox tells TeX that what follows is a box. Just drop \newbox\Rainbox from the above example to see what happens. –  Jan 12 '20 at 22:57

1 Answers1

7

The definition reads

% latex.ltx, line 339:
\def\newbox   {\e@alloc\box
                  {\ifnum\allocationnumber<\@cclvi
                     \expandafter\chardef
                   \else
                     \expandafter\e@alloc@chardef
                   \fi}
                                        {\count14}\insc@unt\float@count}

Uh, not really helpful, is it? OK, we know that \newbox should be followed by a control sequence name, let's say it's \foo. We need to look at \e@alloc:

% latex.ltx, line 386:
\def\e@alloc#1#2#3#4#5#6{%
  \global\advance#3\@ne
  \e@ch@ck{#3}{#4}{#5}#1%
  \allocationnumber#3\relax
  \global#2#6\allocationnumber
  \wlog{\string#6=\string#1\the\allocationnumber}}%

Well it takes six arguments. Let's see what they are when we call \newbox\foo.

  • #1 is \box
  • #2 is \ifnum\allocationnumber...\fi
  • #3 is \count14
  • #4 is \insc@unt
  • #5 is \float@count
  • #6 is \foo

The last allocation number for a \box register is \count14 (this can be seen in source2e); so the first step is to increase it by one. Then

\e@ch@ck{\count14}{\ins@count}{\float@count}\box

is executed. I won't get into the details, but this chooses a new number based on already done allocations; one has to take into account that insertions and floats allocate box registers. Anyway, at the end of the process, \allocationnumber is set to the chosen integer value, (unless there is no room for a new box register, which is unlikely as there are 32768 of them; in this case an error will be raised.

In the normal case the next step is performed, that is

\global#2#6\allocationnumber

If the chosen number is less than 256, this becomes

\global\chardef\foo\allocationnumber

otherwise it becomes

\global\mathchardef\foo\allocationnumber

In either case, \foo becomes essentially equivalent to the allocated number.

When \box\foo is called, this will be the same as specifying the box register number (with the advantage we never need to know the precise number).

If you use the recommended LaTeX command, namely \newsavebox{\foo}, an initial step is performed: LaTeX checks whether \foo is not yet defined. In this case \newbox\foo is executed; otherwise an error is raised and the definition is ignored.

This is quite different from other register allocations. For instance, if you do \newlength\foo, this eventually becomes

\skipdef\foo=<number>

where the number is determined in the same way as before. This allows to use \foo in all situations where TeX expects a length or a length register name.

TeX has no \boxdef command, because box registers are rather peculiar and one can use them in a variety of ways:

\box\foo
\copy\foo
\unhbox\foo
\unvbox\foo
\unhcopy\foo
\unvcopy\foo

and so a \boxdef token would be completely useless.

The other usage is \setbox\foo<box specification> by which a box register is populated. Reading the TeXbook or TeX by Topic about this is recommended.

egreg
  • 1,121,712