While reading about packages that allow to hook macros to certain events, I came across this command, \shipout
. Searching on the internet didn't help a lot but if I'm not so wrong it's somehow related to creating new pages (or is it?).
My question is, what is exactly \shipout
, what does it do and how it does what it does? (i.e. what is happening on the low-level in the background)
Best Answer
This is quite easy:
\shipout
is a primitive. Its syntax iswhere ⟨box⟩ is completely specified at page 278 of the TeXbook:
One could, for example, say
and one page in the DVI or PDF file will be created. Of course nobody wants to use
\shipout
this way. Its main usage is in the output routine that is called when TeX decides it has sufficient material for ejecting a full page. The current main vertical list is split at the chosen page break and its contents is packaged into\box255
, which the output routine can act on. For example, the Plain TeX output routine doesso a full page, adorned with headers and footers is shipped out. The contents of
\box255
is massaged by\pagebody
. The output routine in LaTeX is much more complicated.What one can do is redefining
\shipout
so it does other jobs. The oldest macro set that did something like this wasquire.tex
(still available on CTAN and TeX Live)It saves the primitive meaning of
\shipout
in the command\q_oldship
(the macros use_
as a ‘private’ marker) and redefines it to be\q_boat
, which will do some jobs and eventually call\q_oldship
. For instance it could be set up for placing two output pages on the same physical page, or for making sixteen page quires (whence the package name).The package
atbegshi
does similarly. It redefines\shipout
so that it can hook between the call of\shipout
and the actual page ship out.What precisely the primitive
\shipout
does is transforming the vertical list it's fed with into low level printing instructions (DVI or PDF format, according to the value of\pdfoutput
ifpdftex
orluatex
is used, XDV ifxetex
is used, only DVI for Knuth TeX). Meanwhile it executes all delayed\write
operations, expanding tokens as it goes: in this way references to the page number are guaranteed to be correct, because they are computed when the page is being shipped out.