Examining TeX
Since KaTeX should aim to be compatible with TeX resp. LaTeX, sometimes it becomes important to understand what TeX is doing when processing a given input. Here are some tips of how to do this. Feel free to extend this page as you see fit.
There are essentially two ways how to feed commands into pdflatex or some other TeX engine:
either write the commands to some *.tex file and process that, or launch the process with no arguments,
then you can type arbitrary commands at the * prompts.
In the former case, LaTeX will likely stop after generating some debug output, waiting for you to press enter.
If you want to avoid that, pass --interaction=nonstopmode before the name of the file.
After the run, most information will be contained in the *.log file generated during the run,
while some things are printed to standard output as well.
The command \tracingonline=1 will make more things fall into that latter class.
The \showlists command can be used to show the list of a math
formula before it gets turned into fixed boxes.
\documentclass{article}
\begin{document}
\tracingonline=1
\showboxbreadth=\maxdimen
\showboxdepth=\maxdimen
$1+(2a+3)\showlists$
\end{document}### math mode entered at line 0
\mathord
.\fam0 1
\mathbin
.\fam0 +
\mathopen
.\fam0 (
\mathord
.\fam0 2
\mathord
.\fam1 a
\mathbin
.\fam0 +
\mathord
.\fam0 3
\mathclose
.\fam0 )
In particular, this shows the classification of atoms into the types
ord, op, bin, rel, open, close, punct and inner,
which is required in several places in KaTeX code.
These types control the spacing between atoms,
according to a table in Chapter 18 of The TeX Book.
Things which are not printed as one of these atoms
can be converted according to the rules of Appendix G of that book.
E.g. Rule 8 states that a \vcenter is turned into a \mathord.
If you want to examine the relative dimensions of various items, looking at the box structure may be helpful.
\documentclass{article}
\begin{document}
\tracingonline=1
\showboxbreadth=\maxdimen
\showboxdepth=\maxdimen
\newbox\showy
\setbox\showy=\vbox{$$ 1 + 2 $$}
\showbox\showy
\end{document}You can pipe the result to awk '/> \\box.=/,/^$/{print}'
to extract the box from the rest of the output.
> \box0=
\vbox(18.83333+0.0)x345.0
.\hbox(0.0+0.0)x345.0, glue set 330.0fil
..\hbox(0.0+0.0)x15.0
..\penalty 10000
..\glue(\parfillskip) 0.0 plus 1.0fil
..\glue(\rightskip) 0.0
.\penalty 10000
.\glue(\abovedisplayshortskip) 0.0 plus 3.0
.\glue(\baselineskip) 5.55556
.\hbox(6.44444+0.83333)x22.22217, shifted 161.38892, display
..\OT1/cmr/m/n/10 1
..\glue(\medmuskip) 2.22217 plus 1.11108 minus 2.22217
..\OT1/cmr/m/n/10 +
..\glue(\medmuskip) 2.22217 plus 1.11108 minus 2.22217
..\OT1/cmr/m/n/10 2
.\penalty 0
.\glue(\belowdisplayshortskip) 6.0 plus 3.0 minus 3.0
The trace package can be used to show a lot of details about what is going on internally, while at the same time trying to hide the internals of particularly verbose commands.
This post on the TeX Stack Exchange provides a list of tracing commands which may be used to debug various aspects.
The command \show followed by a macro will display the definition of that macro.
This is best done in interactive mode.
$ pdflatex
**\documentclass{article}
*\show\TeX
> \TeX=macro:
->T\kern -.1667em\lower .5ex\hbox {E}\kern -.125emX\@.
Sometimes the macro is protected to make it robust, in which case the expansion looks almost like the original macro. The difference is that the expanded version contains a trailing space.
There are several ways to examine such macros, e.g. using \csname.
*\show\LaTeX
> \LaTeX=macro:
->\protect \LaTeX .
*\expandafter\show\csname LaTeX \endcsname
> \LaTeX =\long macro:
->L\kern -.36em{\sbox \z@ T\vbox to\ht \z@ {\hbox {\check@mathfonts \fontsize \sf@size \z@ \math@fontsfalse \selectfont A}\vss }}\kern -.15em\TeX .
Most things about TeX are described in The Tex Book by Knuth.
Of course, one can also read the WEB (the programming language)
sources of TeX,
or the document one can create from this using weave tex.web && pdftex tex.
For LaTeX, reading latex.ltx provides the definitions of most commands.
One can also have a look at the documented sources, compiled as source2e.pdf and included in most distributions.
For many math features, amsmath.sty (or the corresponding documented source file amsmath.dtx) and its dependencies are useful starting points.
All these files can be located easily with the help of the kpsewhich command line tool.
As with any TeX package, texdoc -l amsmath will print a list of associated documentation.
