3

Currently learning how to write packages & define custom environments.

In many examples I come across unfamiliar commands (such as \oalign). I so far have had no luck finding their meaning online.

Is there any online guide/repository that has the meaning of all of these commands written down?

Mensch
  • 65,388
Mstislav Keldysh
  • 47

1 Answers1

6

A lot of the code is undocumented. For LaTeX internals, texdoc source2e is your friend¹. For TeX primitives, The TeXbook is an indispensable guide although there are other excellent books available for free online (as mentioned in the comments). Perhaps the most comprehensive account of TeX's internals is Stefan v. Bechtolsheim's four-volume magnum opus, TeX in Practice, although it can be hard to find reasonably priced copies.

Your choice of \oalign is especially notable since this is defined in plain TeX, but only mentioned in the appendix³ where plain.tex is listed in its entirety with some commentary, but not a whole lot. In this instance, \oalign is used to build stacked characters for things like the accents \d (ạ) and \b (ḵ) as well as the copyright symbol ©. The only real ``documentation'' of it is in its usage—see lines 679–690 of plain.tex.

Here's a somewhat modified and abridged version of that section to show how it's used:

\def\oalign#1{%
  \leavevmode % ❶
  \vtop{% ❷
    \baselineskip=0pt% ❸
    \lineskip.25ex% ❸
    \ialign{##\crcr#1\crcr}% ❹
  }%
} 
\def\o@lign{%
   \lineskiplimit=0pt% ❸
   \oalign % ❺
}
\def\d#1{%
  {%
    \o@lign{%
      \relax#1\crcr % ❻
      \hidewidth\sh@ft{-1ex}.\hidewidth % ❼
    }%
  }%
}

The first thing \oalign does is make sure that it's in horizontal mode ❶. In TeX, if you aren't in the middle of a paragraph and you have a box (whether it's an \hbox or \vbox or \vtop or even an \halign, the box will be added to the vertical list instead of starting a new paragraph. \leavevmode starts a new paragraph if we're not already in a paragraph and does nothing if we are.

\vtop ❷ is a vertical box (so it can contain multiple lines) but unlike its close cousin \vbox the baseline of the box will be the baseline of the first line in the box (with \vbox the baseline of the box will be the baseline of the last line in the box).

Then we have a bunch of magic for setting the line skip (cf the lines marked ❸). The spacing between lines is based on three parameters: \baselineskip, \lineskip and \lineskiplimit. Most of the time, the skip from one baseline to another will be \baselineskip⁴. But, if the distance from the top of one line to the bottom of the next is smaller than \lineskiplimit, then \lineskip of extra space will be added.⁵ This is the mechanism that keeps lines of text with super- and subscripts from colliding with each other. The settings here effectively let the characters be printed stacked up with just .25ex of space separating them.⁶

\ialign ❹ is a variation of the primitive \halign for defining tables. It makes sure that \tabskip is 0pt. In this instance, the align is just for stacking up the contents. The \crcr functions similarly to \\ in a LaTeX table for separating lines.⁷ The ##\crcr at the beginning sets a template for the table where the ## stands for the contents of a cell. In this case, we're saying we have a single-column table with no formatting around its contents.

The call to \oalign at the end of the macro ❺ is a common shortcut you'll see in TeX macro definitions. DEK could have defined \o@lign as

\def\o@lign#1{...\oalign{#1}}

but this approach avoids having to copy the argument twice.⁸

The definition of \d lets us see how the underdot is actually set. We call \o@lign⁹ and give it two lines for the alignment: the first ❻ is just the letter we're putting a dot under. The second is the actual dot. The second ❼ sets the underdot. The pair \hidewidth…\hidewidth centers the dot, but allows it to stick out of space reserved for it if necessary.¹⁰ The \sh@ft is there to adjust the position of the character if it appears in italics so that, e.g., ạ will have the correct positioning of the underdot.

  1. From a command line on a computer with TeX and friends installed you can type texdoc xxx where xxx is some package name and get the documentation on the package. In some instances, the documentation includes annotated source code. source2e is the annotated source code² of the LaTeX kernel.
  2. It is, however, very much a work in progress and has been for nearly 30 years. There are sections where the documentation is just the original 2.09 comments which in some cases may be out of date. Other old bits are undocumented or underdocumented. In some cases, the why of some of the code may be lost to the mists of time.
  3. It's sufficiently obscure that my first thought when I saw it was, oh, he must have mistyped \noalign.
  4. Good name.
  5. The default values are 0pt for \lineskiplimit and 1pt for \lineskip.
  6. A definition that I left out for \ooalign sets \lineskiplimit to -\maxdimen, so that the lines will overlap entirely.
  7. This is an oversimplification, much like saying that there are 365 days in a year, but it will do for this discussion.
  8. Philosophically, I like to think of it as a relative to tail-call optimization. After years programming TeX, things like TCO were trivial to conceptualize when I first encountered them.
  9. I'm a bit mystified as to why DEK decided that he would enclose all the calls to \o@lign with braces rather than incorporate the braces into the definition of \o@lign. Not only are all calls executed inside a group, but it is potentially hazardous for them to occur outside a group. ‍♂️
  10. It's difficult to conceive of that happening with the dot of \d, but the similarly defined \b which uses the macron diacritical (¯) positioned below could conceivably be wider than the character it goes beneath. According to Wikipedia, ḻ is used in transcribed Tamil and Seri and proposed for Mapudungun.
Don Hosek
  • 14,078