The \the command

Question

I wanted to know if someone could point me to a reference where I could learn more about the \the command. Searching for "the" has been, without surprise, entirely unproductive. Even consulting "comprehensive" LaTeX command/macro lists has been unfruitful.

This blog is the only treatment of the subject that I could find, but it was not very informative.

Answer 1

The mighty \the

TeX has many registers and internal parameters, whose list can be found in the TeXbook (supplemented by the e-TeX manual and the pdftex manual, for the respective extensions; many more internal parameters are introduced by XeTeX and LuaTeX).

In general, \the\something extracts a representation of the value assigned to \something; the assignment can be explicit (\dimen100=2cm) or implicit (\year is assigned its value at the beginning of the TeX run), in some cases the parameter is "read only" (\badness) and the value stored in it has been assigned during processing.

Registers

In what follows, \something stands for a register of the analyzed type; for example, after \newcount\pippo one can say \the\pippo, or it's an explicitly mentioned register such as \count100 or \dimen0.

1. \count: \the\something extracts the counter's value representation as a number in base 10

2. \dimen: \the\something extracts the stored length representation with unit "typographic point" (pt) as a decimal number, always with at least a digit after the decimal point; for example, after \dimen0=2pt, \the\dimen0 will produce 2.0pt

3. \skip: almost the same as before, but with the additional plus and minus parts (which are omitted if zero)

4. \muskip: the same as \skip, but the units are in mu

5. \toks: this is a very special case, see later

6. \box: also this is a special case, as \the\box0 is illegal (the contents of box registers is accessed at with \box, \copy and related commands such as \unhbox)

Internal parameters

One can use \the\something where \something is an internal parameter; for example, \the\tolerance will behave just like case 1, \the\parindent like in case 2, \the\baselineskip as in case 3, \the\thinmuskip as in case 4, \the\everypar as in case 5. Similarly, \the\day, \the\month, \the\year and \the\time will print the values these internal parameters have been automatically assigned at the start of the job (or modified afterwards). Note that \time is assigned the number of minutes past midnight when the job started (as determined by asking the operating system).

Internal tables

TeX maintains some tables (or vectors): the \catcode table for category codes; the \uccode and \lccode tables for uppercase-lowercase conversion; the \sffcode table for space factors; the \mathcode table for deciding the nature of a character in math mode; the \delcode table for deciding what to do if a character is encountered when TeX is looking for a math fence. In all these cases,

\the<tablename><number>

produces the stored value in place <number> of the vector; the vector's length is 256 in the case of (pdf)TeX, 2^21 in the case of XeTeX and LuaTeX. For example,

\the\catcode123 \the\lccode65

will produce respectively 1 and 97 (with standard settings); of course, the <number> can be expressed in other ways (as octal or hexadecimal number, or as an alphabetical constant). For (pdf)TeX the <number> must be from 0 to 255; for XeTeX and LuaTeX from 0 to 2097151 (hexadecimal 0x1FFFFF).

Special uses

\the can also go before other tokens.

• If we've said \chardef\pippo=37, then \the\pippo will produce 37; similarly for \mathchardef. The representation will be a number in base 10.

• \the\font produces a control sequence that corresponds to the command for selecting the current font; therefore, \xdef\pippo{\the\font} will globally define the command \pippo that will select the font current at the time of \xdef.

• \the\hyphenchar\font, \the\skewchar\font, \the\fontdimen<number>\font will extract the corresponding information for the current font; instead of \font one can use any font selecting command (such as \tenrm in Plain TeX or \OT1/cmr/m/n/10 in LaTeX). For example,

  \the\fontdimen2\csname OT1/cmr/m/n/10\endcsname
  

  will make available the normal interword space for the mentioned font (which is 3.33333pt).

• \the<token register> will produce (a copy of) the token list contained in the <token register>; also internal tokens variables can be used: \the\everypar will produce the token list contained in the stated variable.

Only in the cases of \the\font (but instead of \font can go any font selecting command) and \the<token register> or \the<internal token variable> TeX produces something which is not a string of characters.

When \the produces a string of characters, they will all have category code 12, excepts spaces that receive category code 10.

Important notes

1. \the is expandable. So, while \def\pippo{\count100} and \edef\pippo{\count100} are completely equivalent, \edef\pippo{\the\count100} will define \pippo as the current register's value. If we want to store away the current chapter number in LaTeX, we say \edef\thischapternumber{\the\value{chapter}}.

2. \the will perform expansion on the token following it, stopping only when the next token is a legal one which \the can be applied to. So \the\value{chapter} is possible, as \value{chapter} expands to \csname c@chapter\endcsname and then to \c@chapter (that is a count register defined via \countdef).

3. \the is sometimes superfluous. For example, if we want to keep the current category code of @, in order to restore it after some processing, we might say

   \edef\currentatcatcode{\the\catcode`\@}
   

   but there's a more efficient way:

   \chardef\currentatcatcode=\catcode`\@
   

   Similarly, if we want to take different actions when the badness of the last produced box is less than 5000 or greater than 5000, we can say

   \ifnum\badness<5000
      \dosomething
   \else
      \dosomethingelse
   \fi
   

   Similarly, to set \parindent to the value stored in \normalparindent (a \dimen register allocated in advance), we don't say

   \parindent=\the\normalparindent
   

   but use the easier

   \parindent=\normalparindent
   

Answer 2

The \the primitive is provided by the underlying TeX not by the higher-level LaTeX, therefore it is normally not discussed by LaTeX texts. You would need to read a TeX book like The TeXBook or one of the free TeX books available like TeX by Topic (chapters 12 and 14), or maybe a LaTeX book which explicitly discusses this deeper concepts.

In short \the can only be used in front of a register, either dimen, skip (e.g. a LaTeX length), muskip, count (the underlying register for LaTeX counters) and other numeric expressions like \catcode<number> or toks (token register) as well as special font macros like \font (and maybe others I forget now) and then expands this register to its value in string form. For example \the\textwidth will expand to a string representation of the current text width like 345.0pt. This is useful for writing such information to auxiliary files, print them as part of the document (for e.g. debugging) and for internal conversions.

---

Here the entry from the free book TeX for the Impatient, page 254f:

\the <token>
This command generally expands to a list of character tokens that represents <token>. <token> can be any of the following:

• a TeX parameter, e.g., \parindent or \deadcycles
• a register, e.g., \count0
• a code associated with an input character, e.g., \catcode‘(
• a font parameter, e.g., \fontdimen3\sevenbf
• the \hyphenchar or \skewchar of a font, e.g., \skewchar\teni \lastpenalty, \lastskip, or \lastkern (values derived from the last item on the current horizontal or vertical list)
• a control sequence defined by \chardef or \mathchardef

In addition, \the can expand to noncharacter tokens in the following two cases:

• \the <font>, which expands to the most recently defined control sequence that selects the same font as the control sequence <font>
• \the <token variable>, which expands to a copy of the value of the variable, e.g., \the\everypar