How to use \valign?

Question

I just bumped into a interesting command called \valign. It seems to be the sister of \halign, but the TeXbook seems to be rather shy on explaining its use. As is the TeX by Topic. They only mention it swaps the meaning of rows and columns in its use when compared to \halign. But given the following example:

\valign{&#\cr
How  & is\cr
this & supposed\cr
to   & work?\cr
}
\bye

the produced box is overfull; the second column starts only after the right margin!

So my question is: how is it supposed to be used; how can you change the start of the second (or third) column so it doesn't go out of the page? Also if you have some usage examples somewhere, that'd be great!

Answer 1

The short answer is that each entry is typeset in internal vertical mode, which implies that when you feed it horizontal mode material, as you have done, you get that material typeset as paragraphs, resulting in boxes of width \hsize. Hence the overfill you have noticed. Here is a slightly improved version of your example:

\valign{&\vfil\vbox{\parindent=0pt\hsize=20mm #}\vfil\cr
How  & is is is is is is is is is is is is is\cr
this & supposed\cr
to to to to to to to to to to to to to to to to  & work?\cr
}
\bye

As for a real-life useful example, I haven't got one (other than the single row example \valign{\vfil#\vfil\cr…} mentioned in the TeX book). Maybe someone else will have one.

Answer 2

An example from David Bausum's book

\valign{&\hbox to 1in{\vrule height9pt depth3pt width0pt#\hfil}\vfil\cr
badness  & box& boxmaxdepth& cleaders& dp& everyhbox\cr
everyvbox& hbadness& hbox& hfuzz& hrule& ht& lastbox\cr
leaders& overfullrule& prevdepth& setbox& unhbox& unhcopy& unvbox\cr
unvcopy& vbadness& vbox& vfuzz& vrule& vsplit& vtop\cr
wd& xleaders\cr}
\bye

Answer 3

Here's a modification of Herbert's example that places each entry in an \hbox of natural width and then inserts \hfil between all of the columns by redefining \cr.

\def\cr{\crcr\noalign{\hfil}}
\valign{&\hbox{\strut#}\crcr
badness  & box& boxmaxdepth& cleaders& dp& everyhbox\cr
everyvbox& hbadness& hbox& hfuzz& hrule& ht& lastbox\cr
leaders& overfullrule& prevdepth& setbox& unhbox& unhcopy& unvbox\cr
unvcopy& vbadness& vbox& vfuzz& vrule& vsplit& vtop\cr
wd& xleaders\cr}
\unskip
\bye

Note the final \crcr that ends the alignment preamble and the \unskip that follows. The \unskip could be removed and the final \cr changed to a \crcr.

That same trick could be used to stick a fixed amount of space between columns (note that \tabskip glue goes between rows here) or the not-very-well-known \hbox spread construct can be used. This inserts an extra em of space between columns.

\valign{&\hbox spread1em{\strut#\hfil}\cr
badness  & box& boxmaxdepth& cleaders& dp& everyhbox\cr
everyvbox& hbadness& hbox& hfuzz& hrule& ht& lastbox\cr
leaders& overfullrule& prevdepth& setbox& unhbox& unhcopy& unvbox\cr
unvcopy& vbadness& vbox& vfuzz& vrule& vsplit& vtop\cr
wd& xleaders\cr}
\bye

It's worth pointing out that by starting the alignment with a &, it causes the entire preamble to be repeated.