TeX: Reference and Examples by David Bausum

TeX Primitive Control Sequences
(Alphabetical Order)

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

top a b c d e f g h i j k l m n o p r s t u v w x y (family order)

Control Sequences | Type | Description
\] (control space) | c | inserts a control space.
- (discretionary hyphen) | d | inserts a discretionary hyphen.
/ (italic correction) | c | inserts an italic correction.

top a b c d e f g h i j k l m n o p r s t u v w x y (family order)

Control Sequences | Type | Description
above | d | is equivalent to `\abovewithdelims..'.
abovedisplayshortskip | pg | is alternate glue placed before a displayed equation.
abovedisplayskip | pg | is normal glue placed before a displayed equation.
abovewithdelims | c | is a generalized fraction command.
accent | c | places an accent on a character.
adjdemerits | pi | holds the demerits for visually incompatible adjacent lines.
advance | c | increases or decreases a numeric variable.
afterassignment | c | saves a token and inserts it after the next assignment.
aftergroup | c | saves a token and inserts it after the current group is complete.
atop | d | is equivalent to `\atopwithdelims..'.
atopwithdelims | d | is a generalized fraction command with an invisible fraction bar.

top a b c d e f g h i j k l m n o p r s t u v w x y (family order)

Control Sequences | Type | Description
badness | iq | is 0-10,000 and represents the badness of the glue settings in the last constructed box.
baselineskip | pg | is glue added between lines to keep their baselines consistently spaced.
batchmode | c | acts like pressing Q in response to an error.
begingroup | c | starts a group that must be ended by \endgroup.
belowdisplayshortskip | pg | is alternate glue placed after a displayed equation.
belowdisplayskip | pg | is normal glue placed after a displayed equation.
binoppenalty | pi | is the penalty for a line break after a binary operation.
botmark | c | is the mark text most recently encountered on a page.
box | c | puts the box's contents in the current list and empties the box.
boxmaxdepth | pd | is the maximum possible depth of a vertical box.
brokenpenalty | pi | is the penalty added after a line ending with an hyphenated word.

top a b c d e f g h i j k l m n o p r s t u v w x y (family order)

Control Sequences | Type | Description
catcode | iq | holds the category code for a character.
char | c | provides access to one of the 256 characters in a font.
chardef | iq | provides an alternate way to define a control sequence that returns a character.
cleaders | c | insert centered leaders.
closein | c | closes an auxiliary file opened for reading.
closeout | c | closes an auxiliary file opened for writing.
clubpenalty | pi | is the penalty added after the first line in a paragraph.
copy | c | puts the box's contents in the current list but does not empty the box.
count | iq | assigns an integer to a \count register.
countdef | c | creates a symbolic name for a \count register.
cr | c | is a visible command which ends one row in a table.
crcr | c | is an alternate to \cr.
csname | c | forms a control sequence name from the characters making up a collection of tokens.

top a b c d e f g h i j k l m n o p r s t u v w x y (family order)

Control Sequences | Type | Description
day | pi | holds the current day of the month (1-31).
deadcycles | iq | is the number of times \output was called since the last \shipout.
def | c | defines a macro.
defaulthyphenchar | pi | is the \hyphenchar value to use when a new font is loaded.
defaultskewchar | pi | is -1 or the \skewchar value for a font when it is loaded.
delcode | iq | is -1 or the delimiter code for a character.
delimiter | c | specifies a delimiter.
delimiterfactor | pi | is the first parameter used to compute the size of delimeters required by \left and \right.
delimitershortfall | pd | is the second parameter used to compute the size of delimeters required by \left and \right.
dimen | iq | assigns a <dimen> to a \dimen register.
dimendef | c | creates a symbolic name for a \dimen register.
discretionary | c | specifies a discretionary break in a paragraph.
displayindent | pd | is the amount to shift a line holding a displayed equation.
displaylimits | c | restores normal conventions for using limits with operators.
displaystyle | c | selects display style: D or D'.
displaywidowpenalty | pi | is the penalty added after the penultimate line immediately preceeding a display.
displaywidth | pd | is the width of the line holding a displayed equation.
divide | c | divides a register by an integer.
doublehyphendemerits | pi | holds the demerits added if two consecutive lines end with discretionary breaks.
dp | iq | is the depth of a box.
dump | c | outputs a format file in INITEX; otherwise it is equivalent to \end.

top a b c d e f g h i j k l m n o p r s t u v w x y (family order)

Control Sequences | Type | Description
edef | c | is similar to \def, except control sequences in the replacement text are expanded when the definition is made.
else | c | begins the false part of a conditional.
emergencystretch | pd | is glue used in the third pass made for bad paragraphs.
end | c | terminates the current job.
endcsname | c | is used with \csname to make a control sequence name.
endgroup | c | ends a group that was begun by \begingroup.
endinput | c | stops input from a file at the end of the current line.
endlinechar | pi | is the character added to the end of input lines.
eqno | c | puts an equation number at the right-hand margin.
errhelp | pt | is text displayed on the terminal if h is pressed after an \errmessage.
errmessage | c | displays text on the terminal and interrupts the program.
errorcontextlines | pi | is the number of lines to display on the terminal at an error.
errorstopmode | c | switches to normal interaction for processing errors.
escapechar | pi | is the character used for category 0 characters when outputting control sequences.
everycr | pt | holds tokens inserted after every \cr or nonredundent \crcr.
everydisplay | pt | holds tokens inserted at the start of every switch to display math mode.
everyhbox | pt | holds tokens inserted at the start of every hbox.
everyjob | pt | holds tokens which are inserted at the start of every job.
everymath | pt | holds tokens inserted at the start of every switch to math mode.
everypar | pt | holds tokens added at the beginning of every paragraph.
everyvbox | pt | holds tokens inserted at the start of every vbox.
exhyphenpenalty | pi | is the penalty for a line break after an explicit hyphen.
expandafter | c | `<token1><token2>' is equivalent to `<token1> expansion of <token2>'.

top a b c d e f g h i j k l m n o p r s t u v w x y (family order)

Control Sequences | Type | Description
fam | pi | if 0-15, specifies the font family of class 7 (variable) math symbols.
fi | c | is the concluding command of a conditional.
finalhyphendemerits | pi | holds the demerits added if the penultimate line in a paragraph ends with a discretionary break.
firstmark | c | is the mark text first encountered on a page.
floatingpenalty | pi | is the penalty for insertions that are split between pages.
font | iq | loads information about a font into TeX's memory.
fontdimen | iq | holds font parameters.
fontname | c | returns the system file name for a font.
futurelet | c | `<cs> <token1> <token2>' is equivalent to `\let <cs> = <token2> <token1> <token2>'.

top a b c d e f g h i j k l m n o p r s t u v w x y (family order)

Control Sequences | Type | Description
gdef | d | is equivalent to `\global\def'.
global | c | is an assignment prefix which makes the assignment transcend its group.
globaldefs | pi | if positive, all assignments are global; if negative, \global is ignored.

top a b c d e f g h i j k l m n o p r s t u v w x y (family order)

Control Sequences | Type | Description
halign | c | begins the horizontal alignment of material (i.e., makes a table containing rows).
hangafter | pi | is the number of lines before hanging indentation changes.
hangindent | pd | is the amount of hanging indentation.
hbadness | pi | is the badness above which bad hboxes are reported.
hbox | c | constructs a box holding horizontal material.
hfil | d | inserts first order infinitely stretchable horizontal glue in a horizontal or math list.
hfill | d | inserts second order infinitely stretchable horizontal glue in a horizontal or math list.
hfilneg | d | cancels the stretchability of \hfil.
hfuzz | pd | is the overrun allowed before overfull hboxes are reported.
hoffset | pd | is a value added to the default 1-inch left margin.
holdinginserts | pi | is positive if insertions should remain dormant when \output is called.
hrule | c | makes a rule box in vertical mode.
hsize | pd | is the width of normal lines in a paragraph.
hskip | c | inserts horizontal glue in a horizontal or math list.
hss | d | inserts infinitely stretchable and shrinkable horizontal glue in a horizontal or math list.
ht | iq | is the height of a box.
hyphenation | c | adds words to the hyphenation exception dictionary for the current language.
hyphenchar | iq | holds the current hyphen character used with hyphenation.
hyphenpenalty | pi | is the penalty for a line break after a discretionary hyphen.

top a b c d e f g h i j k l m n o p r s t u v w x y (family order)

Control Sequences | Type | Description
if | c | tests if two tokens have the same character codes (i.e., values 0-256).
ifcase | c | begins a multi-case conditional.
ifcat | c | tests if two tokens have the same category codes (i.e., values 0-16).
ifdim | c | compares two dimensions.
ifeof | c | tests for the end of a file.
iffalse | c | is a conditional which is always false.
ifhbox | c | is true if a box register contains an \hbox.
ifhmode | c | is true if TeX is in horizontal or restricted horizontal mode.
ifinner | c | is true if TeX is in internal vertical, restricted horizontal, or nondisplay math mode.
ifmmode | c | is true if TeX is in math or display math mode.
ifnum | c | compares two integers.
ifodd | c | tests for an odd integer.
iftrue | c | is a conditional which is always true.
ifvbox | c | is true if a box register contains a \vbox.
ifvmode | c | is true if TeX is in vertical or internal vertical mode.
ifvoid | c | is true if a box register is void.
ifx | c | tests if two tokens are the same.
ignorespaces | c | makes TeX read and expand tokens but do nothing until a nonspace token is reached.
immediate | c | performs the following output command without waiting for \shipout.
indent | c | begins a new paragraph indented by \parindent.
input | c | inserts a file at the current position in the source file.
inputlineno | iq | holds the line number of the line last read in the current input file.
insert | c | places material into an insertions class.
insertpenalties | iq | is a quantity used by TeX in two different ways.
interlinepenalty | pi | is the penalty added between lines in a paragraph.

top a b c d e f g h i j k l m n o p r s t u v w x y (family order)

Control Sequences | Type | Description
jobname | c | is the underlying file name for a job.

top a b c d e f g h i j k l m n o p r s t u v w x y (family order)

Control Sequences | Type | Description
kern | c | adds a kern item to the current list.

top a b c d e f g h i j k l m n o p r s t u v w x y (family order)

Control Sequences | Type | Description
language | pi | selects a language to use with hyphenation and \patterns.
lastbox | c | is void or the last hbox or vbox on the current list.
lastkern | iq | is 0.0 pt or the last kern on the current list.
lastpenalty | iq | is 0 or the last penalty on the current list.
lastskip | iq | is 0.0 pt or the last glue or muglue on the current list.
lccode | iq | holds the lowercase value for a character.
leaders | c | fill space using specified glue with a box or rule.
left | c | makes TeX calculate the size of the delimiter needed at the left of a subformula.
lefthyphenmin | pi | is the minimum number of characters that must appear before the first hyphen in an hyphenated word.
leftskip | pg | is glue added at the left of every line in a paragraph.
leqno | c | puts an equation number at the left-hand margin.
let | c | gives a control sequence a token's current meaning.
limits | c | displays limits above and below large operators (class 1).
linepenalty | pi | is an amount added to the \badness calculated for every line in a paragraph.
lineskip | pg | is alternate interline glue used if the \baselineskip glue is not feasible.
lineskiplimit | pd | is the cutoff used to select between \baselineskip and \lineskip.
long | c | is a prefix for definitions which require multi-paragraph arguments.
looseness | pi | tells TeX to try and increase or decrease the number of lines in a paragraph.
lower | c | shifts a box down and appends it to the current horizontal or math list.
lowercase | c | converts tokens to lowercase.

top a b c d e f g h i j k l m n o p r s t u v w x y (family order)

Control Sequences | Type | Description
mag | pi | holds the magnification ratio times 1000.
mark | c | specifies text which should be marked.
mathaccent | c | makes an accent atom from the mathchar and the following item.
mathbin | c | assigns class 2 (binary operation) to the following character or subformula.
mathchar | c | specifies a math character by giving its class, family, and font position.
mathchardef | d | provides an alternate way to define a control sequence that returns a math character.
mathchoice | c | specifies specific subformulas for the 4 main styles.
mathclose | c | assigns class 5 (closing) to the following character or subformula.
mathcode | iq | holds the math character (15-bit number) for each of the 256 characters with which TeX works.
mathinner | c | makes an inner atom holding the math field.
mathop | c | assigns class 1 (large operator) to following character or subformula.
mathopen | c | assigns class 4 (opening) to following character or subformula.
mathord | c | assigns class 0 (ordinary) to following character or subformula.
mathpunct | c | assigns class 6 (punctuation) to following character or subformula.
mathrel | c | assigns class 3 (relation) to following character or subformula.
mathsurround | pd | is extra space added when switching in and out of math mode.
maxdeadcycles | pi | is the maximum allowed value of \deadcycles before an error is generated.
maxdepth | pd | is the maximum depth of boxes on the main page.
meaning | c | adds characters describing a token to the output stream.
medmuskip | pm | is ``medium'' math glue inserted into formulas.
message | c | writes an expanded token list on the terminal and to the log file.
mkern | c | adds a math kern item to the current math list.
month | pi | holds the current month of the year (1-12).
moveleft | c | shifts a box left and appends it to the current vertical list.
moveright | c | shifts a box right and appends it to the current vertical list.
mskip | c | adds math glue to the current math list.
multiply | c | multiplies a register by an integer.
muskip | iq | assigns <muglue> to a \muskip register.
muskipdef | c | creates a symbolic name for a \muskip register.

top a b c d e f g h i j k l m n o p r s t u v w x y (family order)

Control Sequences | Type | Description
newlinechar | pi | is the character which begins a new line of output.
noalign | c | inserts vertical mode material after a \cr in a table.
noboundary | c | if present, breaks ligatures and kerns.
noexpand | c | prevents the expansion of the following token.
noindent | c | begins a new paragraph that is not indented.
nolimits | c | displays limits to the right of large operators (class 1).
nonscript | c | ignores immediately following glue or kern in script and scriptscript styles.
nonstopmode | c | acts like pressing R in response to an error.
nulldelimiterspace | pd | is the width of a null or missing delimiter.
nullfont | iq | is a predefined font with no characters.
number | c | produces the decimal equivalent of numbers.

top a b c d e f g h i j k l m n o p r s t u v w x y (family order)

Control Sequences | Type | Description
omit | c | is used in the body of a table to change an entry's template from the one in the preamble.
openin | c | opens an auxiliary file for reading.
openout | c | opens an auxiliary file for writing.
or | c | separates cases in an \ifcase conditional.
outer | c | is a prefix for a definition which restricts where the definition may be used.
output | pt | holds the token list used to typeset one page.
outputpenalty | pi | holds the penalty from the current page break.
over | d | is equivalent to `\overwithdelims..'.
overfullrule | pd | is the width of the rule appended to an overfull box.
overline | c | puts a line over the following character or subformula.
overwithdelims | d | is a generalized fraction command with preset fraction bar thickness.

top a b c d e f g h i j k l m n o p r s t u v w x y (family order)

Control Sequences | Type | Description
pagedepth | iq | is the actual depth of the last box on the main page.
pagefilllstretch | iq | is the amount of third-order infinite stretchability in the current page.
pagefillstretch | iq | is the amount of second-order infinite stretchability in the current page.
pagefilstretch | iq | is the amount of first-order infinite stretchability in the current page.
pagegoal | iq | is the desired height of the current page.
pageshrink | iq | is the amount of finite shrinkability in the current page.
pagestretch | iq | is the amount of finite stretchability in the current page.
pagetotal | iq | is the accumulated height of the current page.
par | c | is an explicit command to end a paragraph.
parfillskip | pg | is glue which finishs the last line of a paragraph.
parindent | pd | is the width of indentation at the beginning of a paragraph.
parshape | iq | specifies an arbitrary paragraph shape.
parskip | pg | is extra glue put between paragraphs.
patterns | c | is used in INITEX to add patterns to the pattern dictionary for the current language.
pausing | pi | if positive, the program halts after every line is read from the input file and waits for a response from the user.
penalty | c | adds a penalty to the current list.
postdisplaypenalty | pi | is the penalty added immediately after a math display.
predisplaypenalty | pi | is the penalty added immediately before a math display.
predisplaysize | pd | is the effective width of the line preceeding a displayed equation.
pretolerance | pi | is the acceptable \badness of lines in a paragraph before hyphenation is attempted.
prevdepth | iq | is the depth of the last box added to the current vertical list.
prevgraf | iq | is the number of lines in the paragraph most recently completed or partially completed.

top a b c d e f g h i j k l m n o p r s t u v w x y (family order)

Control Sequences | Type | Description
radical | c | makes a radical atom from the delimiter (27-bit number) and the math field.
raise | c | shifts a box up and appends it to the current horizontal or math list.
read | c | reads one or more lines from an auxiliary file.
relax | c | is a control sequence which typesets nothing.
relpenalty | pi | is the penalty for a line break after a relation.
right | c | makes TeX calculate the size of the delimiter needed at the right of a subformula.
righthyphenmin | pi | is the minimum number of characters that must appear after the last hyphen in an hyphenated word.
rightskip | pg | is glue added at the right of every line in a paragraph.
romannumeral | c | converts a number to lowercase roman numerals.

top a b c d e f g h i j k l m n o p r s t u v w x y (family order)

Control Sequences | Type | Description
scriptfont | iq | specifies the script font for a family.
scriptscriptfont | iq | specifies the scriptscript font for a family.
scriptscriptstyle | c | selects scriptscript style: SS or SS'.
scriptspace | pd | is extra space added after a subscript or a superscript.
scriptstyle | c | selects script style: S or S'.
scrollmode | c | acts like pressing S in response to an error.
setbox | c | assigns an hbox, vbox, or vtop to a box register.
setlanguage | c | inserts a language whatsit in restricted horizontal mode.
sfcode | iq | holds the space factor value for a character.
shipout | c | sends the contents of a box to the dvi file.
show | c | writes a token's definition on the terminal and to the log file.
showbox | c | writes the contents of a box to the log file.
showboxbreadth | pi | is the maximum number of items per level written by \showbox and \showlists.
showboxdepth | pi | is the maximum level written by \showbox and \showlists.
showlists | c | writes information about current lists to the log file.
showthe | c | writes a value on the terminal and to the log file and interrupts the program.
skewchar | iq | is -1 or the character used to fine-tune the positioning of math accents.
skip | iq | assigns <glue> to a \skip register.
skipdef | c | creates a symbolic name for a \skip register.
spacefactor | iq | controls interword spacing.
spaceskip | pg | is alternate interword glue.
span | c | combines adjacent entries in a table into a single entry.
special | c | sends material to the dvi file for special processing.
splitbotmark | c | is the mark text of the last mark in the most recent \vsplit operation.
splitfirstmark | c | is the mark text of the first mark in the most recent \vsplit operation.
splitmaxdepth | pd | is the maximum depth of boxes created by \vsplit.
splittopskip | pg | is special glue placed inside the box created by \vsplit.
string | c | converts a control sequence to characters.

top a b c d e f g h i j k l m n o p r s t u v w x y (family order)

Control Sequences | Type | Description
tabskip | pg | is optional glue put between columns in a table.
textfont | iq | specifies the text font for a family.
textstyle | c | selects text style: T or T'.
the | c | returns character tokens for an internal quantity's or parameter's current value.
thickmuskip | pm | is ``thick'' math glue inserted into formulas.
thinmuskip | pm | is ``thin'' math glue inserted into formulas.
time | pi | holds the current time in minutes after midnight (0-1439).
toks | iq | assigns <replacement text> to a \toks register.
toksdef | c | creates a symbolic name for a \toks register.
tolerance | pi | is the acceptable \badness of lines after hyphenation.
topmark | c | is the value of \botmark on the previous page.
topskip | pg | is special glue added before the first box on each page.
tracingcommands | pi | if positive, writes commands to the log file.
tracinglostchars | pi | if positive, writes characters not in the current font to the log file.
tracingmacros | pi | if positive, writes to the log file when expanding macros and arguments.
tracingonline | pi | if positive, writes diagnostic output to the terminal as well as to the log file.
tracingoutput | pi | if positive, writes contents of shipped out boxes to the log file.
tracingpages | pi | if positive, writes the page-cost calculations to the log file.
tracingparagraphs | pi | if positive, writes a summary of the line-breaking calculations to the log file.
tracingrestores | pi | if positive, writes save-stack details to the log file.
tracingstats | pi | if positive, writes memory usage statistics to the log file.

top a b c d e f g h i j k l m n o p r s t u v w x y (family order)

Control Sequences | Type | Description
uccode | iq | holds the uppercase value for a character.
uchyph | pi | prevents hyphenation of uppercase words unless this is positive.
underline | c | puts a line under the following character or subformula.
unhbox | c | puts unwrapped hbox contents in the current list and empties the box.
unhcopy | c | puts unwrapped hbox contents in the current list but does not empty the box.
unkern | c | removes a kern from the current list.
unpenalty | c | removes a penalty from the current list.
unskip | c | removes a glue item from the current list.
unvbox | c | puts unwrapped vbox contents in the current list and empties the box.
unvcopy | c | puts unwrapped vbox contents in the current list but does not empty the box.
uppercase | c | converts tokens to uppercase.

top a b c d e f g h i j k l m n o p r s t u v w x y (family order)

Control Sequences | Type | Description
vadjust | c | inserts a vertical list between two lines in a paragraph.
valign | c | begins the vertical alignment of material (i.e., makes a table containing columns).
vbadness | pi | is the badness above which bad vboxes are reported.
vbox | c | constructs a box holding vertical material.
vcenter | c | centers material with respect to the axis.
vfil | d | inserts first order infinitely stretchable vertical glue in a vertical list.
vfill | d | inserts second order infinitely stretchable vertical glue in a vertical list.
vfilneg | d | cancels the stretchability of \vfil.
vfuzz | pd | is the overrun allowed before overfull vboxes are reported.
voffset | pd | is a value added to the default 1-inch top margin.
vrule | c | makes a rule box in horizontal mode.
vsize | pd | is the desired height of the current page.
vskip | c | inserts vertical glue in a vertical list.
vsplit | c | removes a specified amount of material from a box register.
vss | d | insert infinitely stretchable and shrinkable vertical glue in a vertical list.
vtop | c | is an alternate way to construct a box holding vertical material.

top a b c d e f g h i j k l m n o p r s t u v w x y (family order)

Control Sequences | Type | Description
wd | iq | is the width of a box.
widowpenalty | pi | is the penalty added after the penultimate line in a paragraph.
write | c | writes material to an auxiliary file.

top a b c d e f g h i j k l m n o p r s t u v w x y (family order)

Control Sequences | Type | Description
xdef | d | is equivalent to `\global\edef'.
xleaders | c | insert expanded leaders.
xspaceskip | pg | is alternate intersentence glue.

top a b c d e f g h i j k l m n o p r s t u v w x y (family order)

Control Sequences | Type | Description
year | pi | holds the current year (e.g., 2000).

top a b c d e f g h i j k l m n o p r s t u v w x y (family order)

TeX Primitive Control Sequences
(Family Order)

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

Control Sequences
Family |  | NULL | Type | Description
Box | Logic | - | c | Command
Character | Macro | - | d | Derived Command
Debugging | Marks | - | iq | Internal Quantity
File I/O | Math | - | pi | Parameter (integer)
Fonts | Page | - | pd | Parameter (dimen)
Glue | Paragraph | - | pg | Parameter (glue)
Hyphenation | Penalties | - | pm | Parameter (muglue)
Inserts | Registers | - | pt | Parameter (token)
Job | Tables | - | - | -
Kern | - | - | - | -

top Box Character Debugging File I/O Fonts Glue Hyphenation Inserts Job Kern Logic Macro Marks Math Page Paragraph Penalties Registers Tables (alpha order)

Box | Type | Description
badness | iq | is 0-10,000 and represents the badness of the glue settings in the last constructed box.
box | c | puts the box's contents in the current list and empties the box.
boxmaxdepth | pd | is the maximum possible depth of a vertical box.
cleaders | c | insert centered leaders.
copy | c | puts the box's contents in the current list but does not empty the box.
dp | iq | is the depth of a box.
everyhbox | pt | holds tokens inserted at the start of every hbox.
everyvbox | pt | holds tokens inserted at the start of every vbox.
hbadness | pi | is the badness above which bad hboxes are reported.
hbox | c | constructs a box holding horizontal material.
hfuzz | pd | is the overrun allowed before overfull hboxes are reported.
hrule | c | makes a rule box in vertical mode.
ht | iq | is the height of a box.
lastbox | c | is void or the last hbox or vbox on the current list.
leaders | c | fill space using specified glue with a box or rule.
overfullrule | pd | is the width of the rule appended to an overfull box.
prevdepth | iq | is the depth of the last box added to the current vertical list.
setbox | c | assigns an hbox, vbox, or vtop to a box register.
unhbox | c | puts unwrapped hbox contents in the current list and empties the box.
unhcopy | c | puts unwrapped hbox contents in the current list but does not empty the box.
unvbox | c | puts unwrapped vbox contents in the current list and empties the box.
unvcopy | c | puts unwrapped vbox contents in the current list but does not empty the box.
vbadness | pi | is the badness above which bad vboxes are reported.
vbox | c | constructs a box holding vertical material.
vfuzz | pd | is the overrun allowed before overfull vboxes are reported.
vrule | c | makes a rule box in horizontal mode.
vtop | c | is an alternate way to construct a box holding vertical material.
wd | iq | is the width of a box.
xleaders | c | insert expanded leaders.

top Box Character Debugging File I/O Fonts Glue Hyphenation Inserts Job Kern Logic Macro Marks Math Page Paragraph Penalties Registers Tables (alpha order)

Character | Type | Description
\] (control space) | c | inserts a control space.
accent | c | places an accent on a character.
catcode | iq | holds the category code for a character.
char | c | provides access to one of the 256 characters in a font.
chardef | iq | provides an alternate way to define a control sequence that returns a character.
endlinechar | pi | is the character added to the end of input lines.
escapechar | pi | is the character used for category 0 characters when outputting control sequences.
lccode | iq | holds the lowercase value for a character.
lowercase | c | converts tokens to lowercase.
newlinechar | pi | is the character which begins a new line of output.
number | c | produces the decimal equivalent of numbers.
romannumeral | c | converts a number to lowercase roman numerals.
sfcode | iq | holds the space factor value for a character.
string | c | converts a control sequence to characters.
uccode | iq | holds the uppercase value for a character.
uppercase | c | converts tokens to uppercase.

top Box Character Debugging File I/O Fonts Glue Hyphenation Inserts Job Kern Logic Macro Marks Math Page Paragraph Penalties Registers Tables (alpha order)

Debugging | Type | Description
batchmode | c | acts like pressing Q in response to an error.
errhelp | pt | is text displayed on the terminal if h is pressed after an \errmessage.
errmessage | c | displays text on the terminal and interrupts the program.
errorcontextlines | pi | is the number of lines to display on the terminal at an error.
errorstopmode | c | switches to normal interaction for processing errors.
meaning | c | adds characters describing a token to the output stream.
message | c | writes an expanded token list on the terminal and to the log file.
nonstopmode | c | acts like pressing R in response to an error.
pausing | pi | if positive, the program halts after every line is read from the input file and waits for a response from the user.
scrollmode | c | acts like pressing S in response to an error.
show | c | writes a token's definition on the terminal and to the log file.
showbox | c | writes the contents of a box to the log file.
showboxbreadth | pi | is the maximum number of items per level written by \showbox and \showlists.
showboxdepth | pi | is the maximum level written by \showbox and \showlists.
showlists | c | writes information about current lists to the log file.
showthe | c | writes a value on the terminal and to the log file and interrupts the program.
tracingcommands | pi | if positive, writes commands to the log file.
tracinglostchars | pi | if positive, writes characters not in the current font to the log file.
tracingmacros | pi | if positive, writes to the log file when expanding macros and arguments.
tracingonline | pi | if positive, writes diagnostic output to the terminal as well as to the log file.
tracingoutput | pi | if positive, writes contents of shipped out boxes to the log file.
tracingpages | pi | if positive, writes the page-cost calculations to the log file.
tracingparagraphs | pi | if positive, writes a summary of the line-breaking calculations to the log file.
tracingrestores | pi | if positive, writes save-stack details to the log file.
tracingstats | pi | if positive, writes memory usage statistics to the log file.

top Box Character Debugging File I/O Fonts Glue Hyphenation Inserts Job Kern Logic Macro Marks Math Page Paragraph Penalties Registers Tables (alpha order)

File I/O | Type | Description
closein | c | closes an auxiliary file opened for reading.
closeout | c | closes an auxiliary file opened for writing.
endinput | c | stops input from a file at the end of the current line.
immediate | c | performs the following output command without waiting for \shipout.
input | c | inserts a file at the current position in the source file.
inputlineno | iq | holds the line number of the line last read in the current input file.
openin | c | opens an auxiliary file for reading.
openout | c | opens an auxiliary file for writing.
output | pt | holds the token list used to typeset one page.
read | c | reads one or more lines from an auxiliary file.
shipout | c | sends the contents of a box to the dvi file.
special | c | sends material to the dvi file for special processing.
write | c | writes material to an auxiliary file.

top Box Character Debugging File I/O Fonts Glue Hyphenation Inserts Job Kern Logic Macro Marks Math Page Paragraph Penalties Registers Tables (alpha order)

Fonts | Type | Description
/ (italic correction) | c | inserts an italic correction.
font | iq | loads information about a font into TeX's memory.
fontdimen | iq | holds font parameters.
fontname | c | returns the system file name for a font.
nullfont | iq | is a predefined font with no characters.

top Box Character Debugging File I/O Fonts Glue Hyphenation Inserts Job Kern Logic Macro Marks Math Page Paragraph Penalties Registers Tables (alpha order)

Glue | Type | Description
hfil | d | inserts first order infinitely stretchable horizontal glue in a horizontal or math list.
hfill | d | inserts second order infinitely stretchable horizontal glue in a horizontal or math list.
hfilneg | d | cancels the stretchability of \hfil.
hskip | c | inserts horizontal glue in a horizontal or math list.
hss | d | inserts infinitely stretchable and shrinkable horizontal glue in a horizontal or math list.
lastskip | iq | is 0.0 pt or the last glue or muglue on the current list.
unskip | c | removes a glue item from the current list.
vfil | d | inserts first order infinitely stretchable vertical glue in a vertical list.
vfill | d | inserts second order infinitely stretchable vertical glue in a vertical list.
vfilneg | d | cancels the stretchability of \vfil.
vskip | c | inserts vertical glue in a vertical list.
vss | d | insert infinitely stretchable and shrinkable vertical glue in a vertical list.

top Box Character Debugging File I/O Fonts Glue Hyphenation Inserts Job Kern Logic Macro Marks Math Page Paragraph Penalties Registers Tables (alpha order)

Hyphenation | Type | Description
- (discretionary hyphen) | d | inserts a discretionary hyphen.
defaulthyphenchar | pi | is the \hyphenchar value to use when a new font is loaded.
discretionary | c | specifies a discretionary break in a paragraph.
hyphenation | c | adds words to the hyphenation exception dictionary for the current language.
hyphenchar | iq | holds the current hyphen character used with hyphenation.
language | pi | selects a language to use with hyphenation and \patterns.
lefthyphenmin | pi | is the minimum number of characters that must appear before the first hyphen in an hyphenated word.
patterns | c | is used in INITEX to add patterns to the pattern dictionary for the current language.
righthyphenmin | pi | is the minimum number of characters that must appear after the last hyphen in an hyphenated word.
setlanguage | c | inserts a language whatsit in restricted horizontal mode.
uchyph | pi | prevents hyphenation of uppercase words unless this is positive.

top Box Character Debugging File I/O Fonts Glue Hyphenation Inserts Job Kern Logic Macro Marks Math Page Paragraph Penalties Registers Tables (alpha order)

Inserts | Type | Description
holdinginserts | pi | is positive if insertions should remain dormant when \output is called.
insert | c | places material into an insertions class.
insertpenalties | iq | is a quantity used by TeX in two different ways.
splitbotmark | c | is the mark text of the last mark in the most recent \vsplit operation.
splitfirstmark | c | is the mark text of the first mark in the most recent \vsplit operation.
splitmaxdepth | pd | is the maximum depth of boxes created by \vsplit.
splittopskip | pg | is special glue placed inside the box created by \vsplit.
vsplit | c | removes a specified amount of material from a box register.

top Box Character Debugging File I/O Fonts Glue Hyphenation Inserts Job Kern Logic Macro Marks Math Page Paragraph Penalties Registers Tables (alpha order)

Job | Type | Description
day | pi | holds the current day of the month (1-31).
deadcycles | iq | is the number of times \output was called since the last \shipout.
dump | c | outputs a format file in INITEX; otherwise it is equivalent to \end.
end | c | terminates the current job.
everyjob | pt | holds tokens which are inserted at the start of every job.
jobname | c | is the underlying file name for a job.
mag | pi | holds the magnification ratio times 1000.
maxdeadcycles | pi | is the maximum allowed value of \deadcycles before an error is generated.
month | pi | holds the current month of the year (1-12).
time | pi | holds the current time in minutes after midnight (0-1439).
year | pi | holds the current year (e.g., 2000).

top Box Character Debugging File I/O Fonts Glue Hyphenation Inserts Job Kern Logic Macro Marks Math Page Paragraph Penalties Registers Tables (alpha order)

Kern | Type | Description
kern | c | adds a kern item to the current list.
lastkern | iq | is 0.0 pt or the last kern on the current list.
lower | c | shifts a box down and appends it to the current horizontal or math list.
moveleft | c | shifts a box left and appends it to the current vertical list.
moveright | c | shifts a box right and appends it to the current vertical list.
raise | c | shifts a box up and appends it to the current horizontal or math list.
unkern | c | removes a kern from the current list.

top Box Character Debugging File I/O Fonts Glue Hyphenation Inserts Job Kern Logic Macro Marks Math Page Paragraph Penalties Registers Tables (alpha order)

Logic | Type | Description
else | c | begins the false part of a conditional.
fi | c | is the concluding command of a conditional.
if | c | tests if two tokens have the same character codes (i.e., values 0-256).
ifcase | c | begins a multi-case conditional.
ifcat | c | tests if two tokens have the same category codes (i.e., values 0-16).
ifdim | c | compares two dimensions.
ifeof | c | tests for the end of a file.
iffalse | c | is a conditional which is always false.
ifhbox | c | is true if a box register contains an \hbox.
ifhmode | c | is true if TeX is in horizontal or restricted horizontal mode.
ifinner | c | is true if TeX is in internal vertical, restricted horizontal, or nondisplay math mode.
ifmmode | c | is true if TeX is in math or display math mode.
ifnum | c | compares two integers.
ifodd | c | tests for an odd integer.
iftrue | c | is a conditional which is always true.
ifvbox | c | is true if a box register contains a \vbox.
ifvmode | c | is true if TeX is in vertical or internal vertical mode.
ifvoid | c | is true if a box register is void.
ifx | c | tests if two tokens are the same.
or | c | separates cases in an \ifcase conditional.

top Box Character Debugging File I/O Fonts Glue Hyphenation Inserts Job Kern Logic Macro Marks Math Page Paragraph Penalties Registers Tables (alpha order)

Macro | Type | Description
afterassignment | c | saves a token and inserts it after the next assignment.
aftergroup | c | saves a token and inserts it after the current group is complete.
begingroup | c | starts a group that must be ended by \endgroup.
csname | c | forms a control sequence name from the characters making up a collection of tokens.
def | c | defines a macro.
edef | c | is similar to \def, except control sequences in the replacement text are expanded when the definition is made.
endcsname | c | is used with \csname to make a control sequence name.
endgroup | c | ends a group that was begun by \begingroup.
expandafter | c | `<token1><token2>' is equivalent to `<token1> expansion of <token2>'.
futurelet | c | `<cs> <token1> <token2>' is equivalent to `\let <cs> = <token2> <token1> <token2>'.
gdef | d | is equivalent to `\global\def'.
global | c | is an assignment prefix which makes the assignment transcend its group.
globaldefs | pi | if positive, all assignments are global; if negative, \global is ignored.
let | c | gives a control sequence a token's current meaning.
long | c | is a prefix for definitions which require multi-paragraph arguments.
noexpand | c | prevents the expansion of the following token.
outer | c | is a prefix for a definition which restricts where the definition may be used.
relax | c | is a control sequence which typesets nothing.
the | c | returns character tokens for an internal quantity's or parameter's current value.
xdef | d | is equivalent to `\global\edef'.

top Box Character Debugging File I/O Fonts Glue Hyphenation Inserts Job Kern Logic Macro Marks Math Page Paragraph Penalties Registers Tables (alpha order)

Marks | Type | Description
botmark | c | is the mark text most recently encountered on a page.
firstmark | c | is the mark text first encountered on a page.
mark | c | specifies text which should be marked.
topmark | c | is the value of \botmark on the previous page.

top Box Character Debugging File I/O Fonts Glue Hyphenation Inserts Job Kern Logic Macro Marks Math Page Paragraph Penalties Registers Tables (alpha order)

Math | Type | Description
above | d | is equivalent to `\abovewithdelims..'.
abovedisplayshortskip | pg | is alternate glue placed before a displayed equation.
abovedisplayskip | pg | is normal glue placed before a displayed equation.
abovewithdelims | c | is a generalized fraction command.
atop | d | is equivalent to `\atopwithdelims..'.
atopwithdelims | d | is a generalized fraction command with an invisible fraction bar.
belowdisplayshortskip | pg | is alternate glue placed after a displayed equation.
belowdisplayskip | pg | is normal glue placed after a displayed equation.
binoppenalty | pi | is the penalty for a line break after a binary operation.
defaultskewchar | pi | is -1 or the \skewchar value for a font when it is loaded.
delcode | iq | is -1 or the delimiter code for a character.
delimiter | c | specifies a delimiter.
delimiterfactor | pi | is the first parameter used to compute the size of delimeters required by \left and \right.
delimitershortfall | pd | is the second parameter used to compute the size of delimeters required by \left and \right.
displayindent | pd | is the amount to shift a line holding a displayed equation.
displaylimits | c | restores normal conventions for using limits with operators.
displaystyle | c | selects display style: D or D'.
displaywidowpenalty | pi | is the penalty added after the penultimate line immediately preceeding a display.
displaywidth | pd | is the width of the line holding a displayed equation.
eqno | c | puts an equation number at the right-hand margin.
everydisplay | pt | holds tokens inserted at the start of every switch to display math mode.
everymath | pt | holds tokens inserted at the start of every switch to math mode.
fam | pi | if 0-15, specifies the font family of class 7 (variable) math symbols.
left | c | makes TeX calculate the size of the delimiter needed at the left of a subformula.
leqno | c | puts an equation number at the left-hand margin.
limits | c | displays limits above and below large operators (class 1).
mathaccent | c | makes an accent atom from the mathchar and the following item.
mathbin | c | assigns class 2 (binary operation) to the following character or subformula.
mathchar | c | specifies a math character by giving its class, family, and font position.
mathchardef | d | provides an alternate way to define a control sequence that returns a math character.
mathchoice | c | specifies specific subformulas for the 4 main styles.
mathclose | c | assigns class 5 (closing) to the following character or subformula.
mathcode | iq | holds the math character (15-bit number) for each of the 256 characters with which TeX works.
mathinner | c | makes an inner atom holding the math field.
mathop | c | assigns class 1 (large operator) to following character or subformula.
mathopen | c | assigns class 4 (opening) to following character or subformula.
mathord | c | assigns class 0 (ordinary) to following character or subformula.
mathpunct | c | assigns class 6 (punctuation) to following character or subformula.
mathrel | c | assigns class 3 (relation) to following character or subformula.
mathsurround | pd | is extra space added when switching in and out of math mode.
medmuskip | pm | is ``medium'' math glue inserted into formulas.
mkern | c | adds a math kern item to the current math list.
mskip | c | adds math glue to the current math list.
muskip | iq | assigns <muglue> to a \muskip register.
muskipdef | c | creates a symbolic name for a \muskip register.
nolimits | c | displays limits to the right of large operators (class 1).
nonscript | c | ignores immediately following glue or kern in script and scriptscript styles.
nulldelimiterspace | pd | is the width of a null or missing delimiter.
over | d | is equivalent to `\overwithdelims..'.
overline | c | puts a line over the following character or subformula.
overwithdelims | d | is a generalized fraction command with preset fraction bar thickness.
postdisplaypenalty | pi | is the penalty added immediately after a math display.
predisplaypenalty | pi | is the penalty added immediately before a math display.
predisplaysize | pd | is the effective width of the line preceeding a displayed equation.
radical | c | makes a radical atom from the delimiter (27-bit number) and the math field.
relpenalty | pi | is the penalty for a line break after a relation.
right | c | makes TeX calculate the size of the delimiter needed at the right of a subformula.
scriptfont | iq | specifies the script font for a family.
scriptscriptfont | iq | specifies the scriptscript font for a family.
scriptscriptstyle | c | selects scriptscript style: SS or SS'.
scriptspace | pd | is extra space added after a subscript or a superscript.
scriptstyle | c | selects script style: S or S'.
skewchar | iq | is -1 or the character used to fine-tune the positioning of math accents.
textfont | iq | specifies the text font for a family.
textstyle | c | selects text style: T or T'.
thickmuskip | pm | is ``thick'' math glue inserted into formulas.
thinmuskip | pm | is ``thin'' math glue inserted into formulas.
underline | c | puts a line under the following character or subformula.
vcenter | c | centers material with respect to the axis.

top Box Character Debugging File I/O Fonts Glue Hyphenation Inserts Job Kern Logic Macro Marks Math Page Paragraph Penalties Registers Tables (alpha order)

Page | Type | Description
hoffset | pd | is a value added to the default 1-inch left margin.
maxdepth | pd | is the maximum depth of boxes on the main page.
pagedepth | iq | is the actual depth of the last box on the main page.
pagefilllstretch | iq | is the amount of third-order infinite stretchability in the current page.
pagefillstretch | iq | is the amount of second-order infinite stretchability in the current page.
pagefilstretch | iq | is the amount of first-order infinite stretchability in the current page.
pagegoal | iq | is the desired height of the current page.
pageshrink | iq | is the amount of finite shrinkability in the current page.
pagestretch | iq | is the amount of finite stretchability in the current page.
pagetotal | iq | is the accumulated height of the current page.
topskip | pg | is special glue added before the first box on each page.
voffset | pd | is a value added to the default 1-inch top margin.
vsize | pd | is the desired height of the current page.

top Box Character Debugging File I/O Fonts Glue Hyphenation Inserts Job Kern Logic Macro Marks Math Page Paragraph Penalties Registers Tables (alpha order)

Paragraph | Type | Description
adjdemerits | pi | holds the demerits for visually incompatible adjacent lines.
baselineskip | pg | is glue added between lines to keep their baselines consistently spaced.
doublehyphendemerits | pi | holds the demerits added if two consecutive lines end with discretionary breaks.
emergencystretch | pd | is glue used in the third pass made for bad paragraphs.
everypar | pt | holds tokens added at the beginning of every paragraph.
finalhyphendemerits | pi | holds the demerits added if the penultimate line in a paragraph ends with a discretionary break.
hangafter | pi | is the number of lines before hanging indentation changes.
hangindent | pd | is the amount of hanging indentation.
hsize | pd | is the width of normal lines in a paragraph.
ignorespaces | c | makes TeX read and expand tokens but do nothing until a nonspace token is reached.
indent | c | begins a new paragraph indented by \parindent.
leftskip | pg | is glue added at the left of every line in a paragraph.
lineskip | pg | is alternate interline glue used if the \baselineskip glue is not feasible.
lineskiplimit | pd | is the cutoff used to select between \baselineskip and \lineskip.
looseness | pi | tells TeX to try and increase or decrease the number of lines in a paragraph.
noboundary | c | if present, breaks ligatures and kerns.
noindent | c | begins a new paragraph that is not indented.
par | c | is an explicit command to end a paragraph.
parfillskip | pg | is glue which finishs the last line of a paragraph.
parindent | pd | is the width of indentation at the beginning of a paragraph.
parshape | iq | specifies an arbitrary paragraph shape.
parskip | pg | is extra glue put between paragraphs.
pretolerance | pi | is the acceptable \badness of lines in a paragraph before hyphenation is attempted.
prevgraf | iq | is the number of lines in the paragraph most recently completed or partially completed.
rightskip | pg | is glue added at the right of every line in a paragraph.
spacefactor | iq | controls interword spacing.
spaceskip | pg | is alternate interword glue.
tolerance | pi | is the acceptable \badness of lines after hyphenation.
vadjust | c | inserts a vertical list between two lines in a paragraph.
xspaceskip | pg | is alternate intersentence glue.

top Box Character Debugging File I/O Fonts Glue Hyphenation Inserts Job Kern Logic Macro Marks Math Page Paragraph Penalties Registers Tables (alpha order)

Penalties | Type | Description
brokenpenalty | pi | is the penalty added after a line ending with an hyphenated word.
clubpenalty | pi | is the penalty added after the first line in a paragraph.
exhyphenpenalty | pi | is the penalty for a line break after an explicit hyphen.
floatingpenalty | pi | is the penalty for insertions that are split between pages.
hyphenpenalty | pi | is the penalty for a line break after a discretionary hyphen.
interlinepenalty | pi | is the penalty added between lines in a paragraph.
lastpenalty | iq | is 0 or the last penalty on the current list.
linepenalty | pi | is an amount added to the \badness calculated for every line in a paragraph.
outputpenalty | pi | holds the penalty from the current page break.
penalty | c | adds a penalty to the current list.
unpenalty | c | removes a penalty from the current list.
widowpenalty | pi | is the penalty added after the penultimate line in a paragraph.

top Box Character Debugging File I/O Fonts Glue Hyphenation Inserts Job Kern Logic Macro Marks Math Page Paragraph Penalties Registers Tables (alpha order)

Registers | Type | Description
advance | c | increases or decreases a numeric variable.
count | iq | assigns an integer to a \count register.
countdef | c | creates a symbolic name for a \count register.
dimen | iq | assigns a <dimen> to a \dimen register.
dimendef | c | creates a symbolic name for a \dimen register.
divide | c | divides a register by an integer.
multiply | c | multiplies a register by an integer.
skip | iq | assigns <glue> to a \skip register.
skipdef | c | creates a symbolic name for a \skip register.
toks | iq | assigns <replacement text> to a \toks register.
toksdef | c | creates a symbolic name for a \toks register.

top Box Character Debugging File I/O Fonts Glue Hyphenation Inserts Job Kern Logic Macro Marks Math Page Paragraph Penalties Registers Tables (alpha order)

Tables | Type | Description
cr | c | is a visible command which ends one row in a table.
crcr | c | is an alternate to \cr.
everycr | pt | holds tokens inserted after every \cr or nonredundent \crcr.
halign | c | begins the horizontal alignment of material (i.e., makes a table containing rows).
noalign | c | inserts vertical mode material after a \cr in a table.
omit | c | is used in the body of a table to change an entry's template from the one in the preamble.
span | c | combines adjacent entries in a table into a single entry.
tabskip | pg | is optional glue put between columns in a table.
valign | c | begins the vertical alignment of material (i.e., makes a table containing columns).

top Box Character Debugging File I/O Fonts Glue Hyphenation Inserts Job Kern Logic Macro Marks Math Page Paragraph Penalties Registers Tables (alpha order)

\] (control space) Character
Command
Synopsis: \] (control space)

Description:

    IN certain situations TeX ignores spaces (e.g., after a control word). In other situations it converts multiple spaces into a single space. A control space is used to force TeX to typeset a space [8]. A control space is required when using \nonfrenchspacing to fix the spacing after periods which occur in the middle of a sentence [74]. Regular spaces and blank lines are ignored in vertical mode. However, a control space in vertical mode begins a new paragraph [87]. In math mode regular spaces are ignored, and a control space is required to separate words [163]. A control space adds the same glue to a horizontal or math list that a <space token> with space factor 1000 adds [285 and 290]. Plain TeX defines \<tab> and \<return> so they return a control space [351]. Verbatim listings often make the space character active (category 13) and set it equal to a control space [381].
Example:

  1. \def\thello{Hello}
  2. \thello World. Whoops! \thello\ World.\par
  3. \thello{} World. {\it\thello} World. {\bf\thello\ } World. {\bf\thello\ }World.
Produces: See typeset version.

Comments:

  • The control space (on line 2) is only one way to add a needed space.
  • Line 3 shows TeX does not remove spaces following a `}'.
  • Note: an unwanted space follows the first bold hello (on line 3).
TeXbook References: 8. Also: 8, 10, 19, 73, 74, 86-87, 154, 163, 167, 283, 285, 290, 323, 351, 381.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

- (discretionary hyphen) Hyphenation
Derived Command
Synopsis: \- (discretionary hyphen)

Description:

    A discretionary hyphen inserts `\discretionary{\char h}{}{}' into a horizontal or math list, provided that h, the \hyphenchar of the current font, is between 0 and 255. Otherwise, it inserts `\discretionary{}{}{}' into the list [455]. If the command occurs in vertical mode, it starts a new paragraph [283]. TeX can break a compound word at an existing hyphen, but it does not apply its hyphenation routine to such words. So, a discretionary hyphen may be required to prevent a bad line break. For example `mass-produced' might need to be changed to `mass-pro\-duced' [96].
Example:

  1. \def\tstoryA{There are cries, sobs, confusion among the people, and at
  2. that moment the cardinal himself, the Grand Inquisitor, passes by the
  3. cathedral. He is an old man . . .}
  4. \def\tstoryB{There are cries, sobs, confusion a\-mong the p\-eople, and
  5. at that moment the cardinal himself, the Grand Inquisitor, passes by
  6. the cathedral. He is an old man . . .}
  7. \setbox0=\vbox{\hsize=2.25in \tstoryA}
  8. \setbox1=\vbox{\hsize=2.25in \tstoryB}
  9. \hbox to \hsize{\box0\hfill\box1}
Produces: See typeset version.

Comments:

  • Line 4 adds a discretionary hyphen to `among' and to `people'.
  • TeX uses one and ignores the second.
TeXbook References: 455. Also: 95, 283, 287, 292, 455.

Related Primitives: discretionary, hyphenchar.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

/ (italic correction) Fonts
Command
Synopsis: \/ (italic correction)

Description:

    EVERY character in every font has a dimension called the italic correction. For most characters and most fonts that dimension is zero. But fonts that slant (e.g., an italics font) may have many characters with a nonzero dimension. In horizontal mode `\/' means ``add an explicit kern using the italic correction for the preceeding character or ligature to the current list'' [14 and 287]. But in math mode `\/' adds a kern of width zero to the current list [292].
Example:

  1. \selffamily AA
  2.        [{\it f}]   [{\it f\/}]   [\/{\it f\/}]   {\it [}f]   {\it [\/}f\/]\par
  3. \bgroup
  4.     \font\rm=cmr12 scaled 2000
  5.     \font\it=cmti12 scaled 2000
  6.     \rm[{\it f}]   [{\it f\/}]   [\/{\it f\/}]   {\it [}f]   {\it [\/}f\/]\par
  7. \egroup\par
  8. [\R0{\it f\/}] [\R1{\it f\/}] [\R2{\it f\/}] [\R3{\it f\/}] [\R4{\it f\/}]
  9. [\R5{\it f\/}] [\R6{\it f\/}] [\R7{\it f\/}] [\R8{\it f\/}] [\R9{\it f\/}]
 10. %\def\R#1{\dimen0=0.05em\multiply\dimen0 by #1\kern\dimen0\relax}
Produces: See typeset version.

Comments:

  • This example uses roman and italics fonts for Caslon 224 and Computer Modern at 24 points.
  • The first [f] (made by lines 2 and 6) shows an instance where the f\/ requires an italic correction. It is added in the second [f].
  • TeX does not provide a pre-character italic correction, and the third [f] shows `[' does not have an italic correction. This is not a problem for CM, but it is for Caslon. It represents something that will need to be lived with or fixed by hand [\R4f].
  • The last two examples show the Caslon [ does not have an italic correction, but the CM one does.
  • Lines 8-9 shows several examples of hand kerning. The author's preference uses \R4. The definition of \R is shown on line 10.
  • One of the lessons here is that changing fonts can introduce subtle problems.
TeXbook References: 14. Also: 14, 64, 287, 292, 306, 382, 455.

Related Primitives: font.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

above Math
Derived Command
Synopsis: \above<dimen>

Description:

    THIS command places the subformula preceeding \above over the subformula following \above. Then it places a rule whose thickness is <dimen> between the two subformulas. The command is a generalization of \over and \atop [143] and a special case of \abovewithdelims [152].
Example:

  1. \def\tabove#1%
  2. {%
  3.      {{2 \over 3}\above#1 {1 \over 6}} =
  4.      {{2 \over 3}\cdot{6 \over 1}} = {12 \over 3} = 4
  5. }
  6. $$\hbox{$\tabove{1pt}$,}\quad
  7.   \hbox{$\tabove{2pt}$,}\quad
  8.   \tabove{1pt},\quad
  9.   \tabove{2pt}$$
Produces: See typeset version.

Comments:

  • Lines 1-5 define a macro which uses \above to typeset an expression that might appear in a fourth or fifth grade mathematics text. The macro has a single parameter which determines the thickness of the main fraction bar used in the first fraction.
  • Lines 6-9 create a display and typeset the expression four times: twice in an \hbox in regular math mode and twice in display math mode.
TeXbook References: 143, 152. Also: 143, 152, 292, 444-445.

Related Primitives: over, atop, abovewithdelims.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

abovedisplayshortskip Math (Glue)
0pt plus 3pt * Parameter (glue)
Synopsis: \abovedisplayshortskip<glue>

Description:

    AFTER TeX processes a math display, it adds the following items to the current vertical list: a penalty, glue, the actual display, glue, and a penalty. The two glue items are either the above and below displayskips or the above and below displayshortskips. The latter are used if: a) the display occurs at the start of a paragraph; b) the display follows another display; or c) the display occurs in the middle of a paragraph but does not have a left equation number and does not overlap the preceeding line of text [189].
Example:

     \def\tfn#1#2#3#4#5% above & below regular & short skips + post-example skip
     {%
        \abovedisplayskip=#1
        \belowdisplayskip=#2
        \abovedisplayshortskip=#3
        \belowdisplayshortskip=#4
        \hfill The Fibonacci numbers are defined\break
        by: $F_0=1$, $F_1=1$, and
        $$F_n = F_{n-1} + F_{n-2} \hbox{, for } n \ge 2.$$
        A related sequence $\{v_n\}$ is: 2, 1, 3, 4, 7, 11, 18, \char144\ It
        satisfies $v_n$ = $x^n + y^n$, where $x = (1 + \sqrt 5)/ 2$
        and $y = (1 - \sqrt 5)/ 2$.
        \vskip#5
     }
     \tfn{12pt}{12pt}{0pt}{0pt}{1\baselineskip}
     \tfn{12pt}{12pt}{3pt}{3pt}{0pt}
Produces: See typeset version.

Comments:

  • These examples are similar to the ones for \abovedisplayskip only this time each example uses short display skips.
  • The examples illustrate the two extremes of the short skip Plain TeX provides.
TeXbook References: 189. Also: 189, 274, 348, 415.

Related Primitives: belowdisplayshortskip, abovedisplayskip.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

abovedisplayskip Math (Glue)
12pt plus 3pt minus 9pt * Parameter (glue)
Synopsis: \abovedisplayskip<glue>

Description:

    AFTER TeX processes a math display, it adds the following items to the current vertical list: a penalty, glue, the actual display, glue, and a penalty. The two glue items are either the above and below displayskips or the above and below displayshortskips. The former are used if: a) the display occurs in the middle of a paragraph and the display overlaps the preceeding line of text; or b) the display has a left equation number [189]. Also, the former are used before and after an alignment display [190].
Example:

     \def\tfn#1#2#3#4#5% above & below regular & short skips + post-example skip
     {%
        \abovedisplayskip=#1
        \belowdisplayskip=#2
        \abovedisplayshortskip=#3
        \belowdisplayshortskip=#4
        The Fibonacci numbers are defined by: $F_0=1$, $F_1=1$, and
        $$F_n = F_{n-1} + F_{n-2} \hbox{, for } n \ge 2.$$
        A related sequence $\{v_n\}$ is: 2, 1, 3, 4, 7, 11, 18, \char144\ It
        satisfies $v_n$ = $x^n + y^n$, where $x = (1 + \sqrt 5)/ 2$
        and $y = (1 - \sqrt 5)/ 2$.
        \vskip#5
     }
     \tfn{3pt}{3pt}{6pt}{6pt}{1\baselineskip}
     \tfn{12pt}{12pt}{6pt}{6pt}{0pt}
Produces: See typeset version.

Comments:

  • This example typesets the same material twice using regular display skips.
  • The first example uses a small value for the glue placed before and after the display. It is what Plain TeX will make if the glue shrinks its maximum amount.
  • The second example shows what Plain TeX will make if the glue neither stretches nor shrinks.
TeXbook References: 189. Also: 189, 190, 194, 274, 291, 348, 415.

Related Primitives: belowdisplayskip, abovedisplayshortskip.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

abovewithdelims Math
Command
Synopsis: \abovewithdelims<delim1><delim2><dimen>

Description:

    THIS command is a generalized form of \above. It builds the same fraction \above does (with a line whose thickness is <dimen>). Then it puts <delim1> before the fraction and <delim2> after it. Both delimiters are scaled appropriately. If a `.' is used for either <delim>, TeX ignores the corresponding delimiter. In fact, \above<dimen> is an abbreviation for `\abovewithdelims..<dimen>'. All the other fraction commands are derived from this command [152].
Example:

  1. \def\legendre{\overwithdelims()}
  2. \def\tlA{\abovewithdelims()0.4pt}
  3. \def\tlB{\abovewithdelims()1.0pt}
  4. \def\tlC{\abovewithdelims()2.0pt}
  5. $a\legendre p$, ${a\tlA p}$, ${a\tlB p}$, and ${a\tlC p}$.
  6. $$\displaylines{{a\legendre p} = +1\hbox{,\quad if\quad}a\hbox{\ R }p,\qquad
  7.            {a\tlA p} = -1\hbox{,\quad if\quad}a\hbox{\ N }p,\qquad
  8.            {a\tlC p} = -1\hbox{,\quad if\quad}a\hbox{\ N }p.\cr}$$
Produces: See typeset version.

Comments:

  • Lines 1-4 define four macros which make a Legendre symbol. The first macro uses \overwithdelims, and each of the remaining three use \abovewithdelims.
  • Line 5 uses each macro to typeset an example in math mode.
  • Lines 6-8 typeset three of the macros in display mode.
TeXbook References: 152. Also: 152, 292, 444-445.

Related Primitives: above, over, atop, overwithdelims, atopwithdelims.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

accent Character
Command
Synopsis: \accent<8-bit number><optional assignments>

Description:

    THIS command places an accent on a character. The <8-bit number> gives the position of the accent in the current font. The accent should be at the correct position for characters whose height is the x-height of the current font. The accent is raised or lowered to fit taller or shorter characters. The width of the result is the width of the character being accented [54]. The <optional assignments> stands for 0 or more assignments [275-278] other than \setbox. The character receiving the accent should be: a character with category code 11 or 12 (letter or other), a \char or \chardef token, or \noboundary. If a character does not follow the assignment, the result is the same as \char<8-bit number> [286]. Otherwise, the character is accented by the accent. After an accent TeX sets \spacefactor=1000 [287]. If \accent appears in vertical mode, a new paragraph is started [283]. Plain TeX sets up the basic accents for Computer Modern fonts [356]. If another font is used which has the accents in different positions, new definitions are required [nr].
Example:

  1. % Accents for 9y encoding of Caslon 224:
  2. \def\'#1{{\accent00 #1}}% acute
  3. \def\u#1{{\accent01 #1}}% breve
  4. \def\v#1{{\accent02 #1}}% hacek or check
  5. \def\^#1{{\accent04 #1}}% circumflex or hat
  6. \def\"#1{{\accent05 #1}}% umlaut
  7. \def\.#1{{\accent06 #1}}% dot (over)
  8. \def\`#1{{\accent07 #1}}% grave
  9. \def\H#1{{\accent08 #1}}% long Hungarian umlaut
 10. \def\=#1{{\accent09 #1}}% macron or bar
 11. \def\r#1{{\accent11 #1}}% ring (open dot over)
 12. \def\~#1{{\accent12 #1}}% tilde
 13. \def\d#1{{\o@lign{\relax#1\crcr\hidewidth\sh@ft{10}.\hidewidth}}}% dot (under)
 14. \def\b#1{{\o@lign{\relax#1\crcr\hidewidth\sh@ft{29}%               bar (under)
 15.     \vbox to.2ex{\hbox{\char09}\vss}\hidewidth}}}
 16. \def\c#1{\setbox\z@\hbox{#1}\dimen\z@=\dp\z@\ifdim\ht\z@=1ex\accent03 #1%cedilla
 17.   \else{\ooalign{\unhbox\z@\crcr\hidewidth\lower0.9\dimen\z@ %
 18.         \hbox{\char03}\hidewidth}}\fi}
 19. \def\o#1{\setbox\z@\hbox{#1}\dimen\z@=\dp\z@\ifdim\ht\z@=1ex\accent10 #1% ogonek
 20.   \else{\ooalign{\unhbox\z@\crcr\hidewidth\lower0.9\dimen\z@ %
 21.         \hbox{\char10}\hidewidth}}\fi}
 22. %
 23. \'A \u B \v C \^D \"E \.F \`H \H I \=J \r K \~L \d M \b N \c O \o P \o A ---
 24. \'a \u b \v c \^d \"e \.f \`g \H h \=k \r l \~m \d n \b o \c p \o q \o a
Produces: See typeset version.

Comments:

  • The ``9y'' encoding is a custom encoding I made for Caslon 224.
  • Lines 2-15 are a direct modification of the Plain TeX macros.
  • Lines 16-18 modify Plain TeX's \c macro by adding the \lower command on line 17.
  • Caslon 224 has an ogonek accent which is not in the Computer Modern fonts. The definition of \o on lines 19-21 is a straightforward modification of \c.
  • Lines 23-24 use each accent to typeset a mixture of upper and lower case letters.
TeXbook References: 286-287, 356. Also: 9, 54, 86, 283, 286.

Related Primitives: char.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

adjdemerits Paragraph
10000 * Parameter (integer)
Synopsis: \adjdemerits=<number>

Description:

    THIS value is added to the demerits calculated for a line, when TeX is breaking a paragraph into lines, if the line and the previous one are visually incompatible [98]. During the break-up, TeX classifies each line as: tight, decent, loose, or very loose. Also, it says two consecutive lines are visually incompatible if their classifications are not adjacent (i.e., a tight line followed by a loose or very loose one, or a decent line followed by a very loose one) [97].
Example:

     \gdef\tstory{There are cries, sobs, confusion among the people, and
     at that moment the cardinal himself, the Grand Inquisitor, passes by the
     cathedral. He is an old man, almost ninety, tall and erect, with a
     withered face and sunken eyes, in which there is still a gleam of light.
     He is not dressed in his brilliant cardinal's robes, as he was the day
     before, when he was burning the enemies of the Roman Church~\char144
     \kern2em\hfill Fyodor Dostoyevsky, {\it The Brothers Karamazov}}
     % The example for several primitives uses \tstory.
     \hsize=2.5in
     \setbox0=\vbox{\adjdemerits=0
     \doublehyphendemerits=100000
     \finalhyphendemerits=900000
     \tstory\par}
     \setbox1=\vbox{\adjdemerits=1000000
     \doublehyphendemerits=100000
     \finalhyphendemerits=900000
     \tstory\par}
     \hbox{\box0\kern0.25in\box1}
Produces: See typeset version.

Comments:

  • This example continues the example on the \finalhyphendemerits reference page.
  • The original paragraph (shown on the \doublehyphendemerits page) had several hyphen-related problems.
  • Those problems are cleared up on the left paragraph. However, it still uses \adjdemerits=0.
  • The paragraph on the right uses a large value for \adjdemerits and is slightly different from the left paragraph.
TeXbook References: 98. Also: +98, 273, @314, @348.

Related Primitives: doublehyphendemerits, finalhyphendemerits.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

advance Registers
Command
Synopsis: \advance<numeric variables> by <quantity>

Description:

    THIS command is used to increase or decrease one of the <numeric variables>. The <quantity> should have a type compatible with the variable as shown in the following:
    \advance<integer variable> by <number>
    \advance<dimen variable> by <dimen>
    \advance<glue variable> by <glue>
    \advance<muglue variable> by <muglue>
    An <integer variable> is: a) an explicit \count register (e.g., \count17); b) a control sequence specified using \countdef, \newcount, or something equivalent; or c) an integer parameter such as \tolerance or \widowpenalty. The dimen, glue, and muglue variables are similar. The ``by'' is optional [118 and 276].
Example:

  1. \def\tpagenumber#1% page number.
  2. {%
  3.   \bgroup
  4.      \count1=#1
  5.      \ifnum\count1 > 0
  6.           \edef\tpageA{\the\count1}%
  7.           \advance\count1 by 1
  8.           \def\tpageB{\the\count1}%
  9.      \else
 10.           \count1=-\count1% This makes the page > 0.
 11.           \edef\tpageA{\romannumeral\count1}%
 12.           \advance\count1 by 1
 13.           \def\tpageB{\romannumeral\count1}%
 14.      \fi
 15.      The current page number is: \tpageA. The next page number is: \tpageB.\par
 16.   \egroup
 17. }
 18. \tpagenumber{127}
 19. \tpagenumber{-15}
Produces: See typeset version.

Comments:

  • This example is not quite complete since the page number is not stored in a useful place.
  • However, it shows one way to increase or decrease a counter and to typeset either the digits in a number or the letters in the roman numeral equivalent of the number.
  • If \def is used instead of \edef on lines 6 and 11, the \tpageA macro will use the same value for \count1 that \tpageB uses.
TeXbook References: 118-119. Also: 21, 118-119, 218, 256, 276, 355.

Related Primitives: multiply, divide, count, dimen, skip, muskip.

For Additional Examples, see: day, ifnum, time

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

afterassignment Macro
Command
Synopsis: \afterassignment<token>

Description:

    THIS command saves <token> (without expansion [215]) and inserts it back into the input after the next assignment. If two \afterassignment commands occur before an assignment, only the second token is saved. If the next assignment is `\setbox n=\hbox{...}', the saved token is inserted immediately after the `{' just before tokens from \everyhbox. Assignments made by \setbox with \vbox or \vtop work the same way [279].
Example:

  1. \def\ttrA#1{[#1]}
  2. \def\ttrB#1%
  3. {%
  4.      \setbox0=\hbox{{\selffamily AD [}}%
  5.      \setbox1=\hbox{{\selffamily AD ]}}%
  6.      \raise0.45\dp0\box0 %
  7.      {\selffamily AE  #1}%
  8.      \raise0.45\dp1\box1 %
  9. }%
 10. \def\trtC#1{\def\tpage{#1}\afterassignment\ttrD\let\next=}
 11. \def\ttrD
 12. {%
 13.      \advance\tnotenumber by 1%
 14.      \unskip
 15.      \if\next.% the working version has other special cases: e.g., `)' `,'.
 16.           .\superscript{\the\tnotenumber}%
 17.      \else
 18.           \R1\superscript{\the\tnotenumber}\ \next
 19.      \fi
 20.      \global\setbox\tnotebox=\hbox
 21.      {%
 22.           \noindent
 23.           \unhbox\tnotebox
 24.           \superscript{\the\tnotenumber}%
 25.           \R1\tpage.\quad
 26.      }%
 27. }
 28. \def\texam#1{#1 --- This example \tr{151} illustrates work-in-progress
 29. \tr{176--177}. Originally, all page references \tr{213 and 217} to
 30. {\it The TeXBook} \tr{399} in the reference pages appeared directly
 31. (e.g., |[151]|) \tr{255}.}
 32. \let\tr=\ttrA
 33. \setbox0=\vbox{\texam1}
 34. \unvbox0\vskip1\baselineskip
 35. \let\tr=\ttrB
 36. \setbox0=\vbox{\texam2}
 37. \unvbox0\vskip1\baselineskip
 38. \let\tr=\trtC
 39. \tnotenumber=0
 40. \setbox\tnotebox=\hbox{}
 41. \setbox0=\vbox{\texam3}
 42. \unvbox0\vskip0.5\baselineskip\unhbox\tnotebox
Produces: See typeset version.

Comments:

  • This is a long example, but it illustrates the power of \afterassignment, \let, \if and TeX in a real situation. The same source (lines 28-31) is made to appear in three distinct ways by changing a formatting routine.
  • The basic question is ``How should page references to The TeXbook appear in the Description area on a reference page?'' The example shows three possibilities.
  • The first paragraph is made by lines 1 and 28-34. In my opinion the brackets and page numbers in it are much too large.
  • The second paragraph is made by lines 2-9, 28-31, and 35-37. I used trial-and-error before deciding on the values used on lines 4-8. Most of the reference pages were completed using this style before I decided there were enough entries like references 2, 3, and 5 to warrant giving the matter more attention.
  • The third paragraph is the result of that attention. In my opinion it provides complete documentation in an unobstructive way.
  • The one wrinkle is that footnotes should come after periods. After some more thought, I realized TeX could swap the period and the footnote on an as needed basis. That is the real point of this example.
  • The third paragraph is made by lines 10-31 and 38-42. The macro \ttrC forms the link between the document and \ttrD which does the typesetting. First, \ttrC saves the reference in a temporary macro. Next, it says: ``read the first token after this macro and put it in \next; then do \ttrD.'' The next token will be a period (for notes 2 and 5) or the character following `}\]' for the other notes (e.g., an `i' for note 1).
  • Line 14 removes the glue made by the space which preceeds each \ttr{} in the paragraph.
  • Line 15 compares \next and `.'. If they are the same, TeX typesets a period and the correct footnote number. Otherwise, it inserts a small amount of glue (the \R1) and typesets the correct footnote number, a control space, and \next (the next token).
  • Lines 20-26 are a quick and dirty way to build the line of references one at a time.
TeXbook References: 279. Also: 215, 279, 352, 364, 376, 401.

Related Primitives: aftergroup, expandafter, futurelet, noexpand.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

aftergroup Macro
Command
Synopsis: \aftergroup<token>

Description:

    THIS command saves <token> on TeX's save stack (without expansion [215]) and inserts it back into the input when the current group ends. If several \aftergroup commands occur in a group, each of the saved tokens is inserted in the same order the commands occurred [279].
Example:

  1. \def\ta{Hello}
  2. \def\tb{ World. }
  3. \def\tc{How are you?}
  4. \begingroup
  5. \aftergroup\ta
  6. \aftergroup\tb
  7. \aftergroup\tc
  8. \let\ua=\tc
  9. \let\ub=\tb
 10. \let\uc=\ta
 11. \gdef\ta{I am}
 12. \gdef\tb{ fine. }
 13. \ua\ub\uc---1---\par
 14. \endgroup
 15. ---2---
Produces: See typeset version.

Comments:

  • Lines 5-7 setup three aftergroup tokens, and lines 11-12 change two of the tokens.
  • When the group ends, all three tokens appear with the correct values.
TeXbook References: 279. Also: 215, 279, 363, 374, 377, 379.

Related Primitives: afterassignment, expandafter, futurelet, noexpand.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

atop Math
Derived Command
Synopsis: \atop

Description:

    THIS command places one subformula over a second subformula, only it doesn't put a line between the two subformulas as \over does [143]. The command is an abbreviation for `\atopwithdelims..' [152].
Example:

  1. $n \atop k = n! / k!(n-k)!,$
  2. \hbox{this doesn't work. It needs a pair of braces.}\par\vskip0.5\baselineskip
  3. ${n \atop k} = n! / k!(n-k)!$, this looks okay, but it is missing ()'s.
  4. $$n \atop k = n! / k!(n-k)!,\quad
  5. \hbox{this doesn't work. It needs a pair of braces.}$$\par
  6. $${n \atop k} = {n! \over k!(n-k)!} = n! / k!(n-k)!,\quad
  7. \hbox{this looks okay, but it is missing the ()'s.}$$
Produces: See typeset version.

Comments:

  • TeX's generalized fraction commands often require braces `{}'. Lines 1 and 4-5 show what happens if a required pair is omitted.
  • Lines 3 and 6-7 show the corrected material.
  • Several of the fractions shown above should be surrounded by parenthesis `()'. They are provided by \atopwithdelims.
TeXbook References: 143, 152. Also: 143, 145, 152, 178, 292, 444.

Related Primitives: over, above, atopwithdelims.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

atopwithdelims Math
Derived Command
Synopsis: \atopwithdelims<delim1><delim2>

Description:

    THIS command is a generalized form of \atop. It builds the same fraction \atop does (without a line). Then, it puts <delim1> before the fraction and <delim2> after it. Both delimiters are scaled appropriately. If a `.' is used for either <delim>, TeX ignores the corresponding delimiter. In fact, \atop is an abbreviation for `\atopwithdelims..'. Also, \atopwithdelims is derived from \abovewithdelims [152].
Example:

  1. \def\tchoose{\atopwithdelims()}
  2. \def\tc#1#2{{#1\tchoose #2}}
  3. $\tc nk = {n \tchoose n-k} = n! / k!(n-k)!$\quad now have needed parenthesis.
  4. $$\displaylines{\hbox{Also,}\qquad{n \tchoose k} = {n! \over k!(n-k)!}=
  5. n!/k!(n-k!).\hfill\cr}$$
  6. {\bf Theorem 75}.\quad If $p$ is a prime, then
  7. $$\tc p1,\ \tc p2,\ldots,\ \tc p{p-1}$$
  8. are divisible by $p$.
Produces: See typeset version.

Comments:

  • Lines 1-2 provide an alternate to Plain TeX's \choose macro.
  • The utility of \tc becomes apparent in the display made by line 7.
TeXbook References: 152. Also: 152, 292, 324, 360, 444.

Related Primitives: atop, abovewithdelims.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

badness Box
Internal Quantity
Synopsis: \badness

Description:

    THIS is an internal quantity set after each box is made. It is between 0 and 10,000 unless the box is overfull. Then it is 1,000,000 [229]. If r is the glue set ratio [77], \badness is approximately min(100r3,10000) [97].
Example:

     \def\badboxes#1#2%
     {%
          \overfullrule=0.25pt
          \setbox0=\hbox spread#2{#1}%
          \count12=\the\badness
          \setbox1=\hbox to 2.5in{\box0\hfil\the\count12}%
          \box1
     }
     \badboxes{The badness of this line is: }{-1em}
     \badboxes{The badness of this line is: }{-0.5em}
     \badboxes{The badness of this line is: }{-0.3em}
     \badboxes{The badness of this line is: }{0em}
     \badboxes{The badness of this line is: }{1em}
     \badboxes{The badness of this line is: }{2em}
     \badboxes{The badness of this line is: }{3em}
Produces: See typeset version.

Comments:

  • The first line with a badness of 1,000,000 has a thin rule after `is: '. It is the rule placed at the end of overfull boxes. Normally, it is 5 points wide, but the \overfullrule command in \badboxes changed the width to 0.25 points.
  • Two of the lines have the same \badness. However, one line is too tight and the other is too loose. So, \badness, by itself, cannot distinguish between tight and loose lines.
TeXbook References: 29, 229. Also: 214, 229, 271.

Related Primitives: hbadness, vbadness, pretolerance, tolerance, emergencystretch.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

baselineskip Paragraph
Parameter (glue)
Synopsis: \baselineskip=<glue>

Description:

    THIS parameter gives the desired glue which should separate boxes in a vertical list [78]. In actual practice TeX uses three other primitives to compute the interline glue placed between boxes: \prevdepth = p, \lineskip, and \lineskiplimit = l. Let the box about to be added have height h, and let \baselineskip = {b plus x minus y}. If p <= -1000pt, no interline glue is added. Otherwise, if b >= p + h + l, the glue `(b-p-h) plus x minus y' is added just before the new box. Otherwise, the \lineskip glue is placed just before the new box. After the new box is added, \prevdepth is set to its depth [80]. Text set using 10-point type often uses `\baselineskip = 12pt'. The same ratio (1.2) works well with point sizes from 7-14 points [nr]. To suppress interline glue between two boxes put `\prevdepth=-1000pt' just before the second one. To suppress interline glue between a number of boxes set `\baselineskip=-\maxdimen', `\lineskiplimit=\maxdimen', and `\lineksip=0pt' before the first box [352].
Example:

     \parindent=2pc \hsize=4.75in% Point size in all examples is 10pt.
     \baselineskip=11.5pt\tstory\par% The \adjdemerits reference page
     \baselineskip=12pt\tstory\par%   holds the definition of \tstory
     \baselineskip=12.5pt\tstory\par
Produces: See typeset version.

Comments:

  • These paragraphs show the effect of a small change in the space put between lines of text. The results are even more striking if several pages are typeset each with its own \baselineskip value.
TeXbook References: 78-80, 281. Also: 78-80, 104, 194, 253, 256, 274, 281, 342, 349, 351-352, 409, 414-415.

Related Primitives: lineskip, lineskiplimit, prevdepth.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

batchmode Debugging
Command
Synopsis: \batchmode

Description:

    NORMALLY, when TeX discovers an error in a file, it stops processing, displays a message on the terminal, and waits for instructions for what to do next. One option at this point is to press Q (run quietly). That tells TeX to continue processing without stopping if further errors arise and to suppress further output to the terminal [31]. If TeX encounters \batchmode in a file, then it begins to process the file just as if Q was entered in response to an error. This is a global change which continues until the end of the file or until one of the other `..mode' commands is encountered [32]. Certain errors cause TeX to stop processing prematurely in \batchmode (e.g., a missing file on an \input statement) [299].
Example:

  1. \batchmode
  2.   .
  3.   .
  4.   .
  5. \errorstopmode
Produces: See typeset version.

Comments:

  • If TeX encounters errors on lines 2-4, it writes an error message to the log file, but it won't display a message on the terminal or stop for user input.
  • After line 5 TeX resumes normal error processing.
TeXbook References: 32. Also: 32, 277, 299, 336.

Related Primitives: errorstopmode, nonstopmode, scrollmode.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

begingroup Macro
Command
Synopsis: \begingroup

Description:

    THIS command begins a new level of grouping. That group must be terminated by \endgroup not by `}'. The mode doesn't change [279]. Groups begun by `{' and \begingroup must be properly nested; `{\begingroup}\endgroup' generates an error [21].
Example:

  1. \catcode`\?=13 % make ? the special character for in-line verbatim
  2. \def?{\begingroup\ccflip\getword}%
  3. \def\getword#1?{#1\endgroup}%
  4. Hello ?\World? How are you\char63\kern2.5pt?\char63? See you later.
Produces: See typeset version.

Comments:

  • Line 1 makes `?' an active character.
  • Line 2 defines `?'. The definition begins a new group; changes the catcodes of the characters used to control TeX ; and calls \getword.
  • Line 3 shows \getword has a single parameter which is ended by a `?'. Thus, everything between the two `?'s gets typeset verbatim\mkindex{verbatim}. The \endgroup on line 3 matches the \begingroup on line 2. When \getword and the group ends, each of the catcodes changed on line 2 reverts to its normal value.
  • Line 4 holds some sample text. Note, the ASCII value of a `?' is 63.
TeXbook References: 21, 279. Also: 21, 249, 262, 279, 380, 407, 419.

Related Primitives: endgroup.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

belowdisplayshortskip Math (Glue)
7pt plus 3pt minus 4pt * Parameter (glue)
Synopsis: \belowdisplayshortskip<glue>

Description:

    AFTER TeX processes a math display, it adds the following items to the current vertical list: a penalty, glue, the actual display, glue, and a penalty. The two glue items are either the above and below displayskips or the above and below displayshortskips. The latter are used if: a) the display occurs at the start of a paragraph; b) the display follows another display; or c) the display occurs in the middle of a paragraph but does not have a left equation number and does not overlap the preceeding line of text [189].
Example:

  1. \def\tfns#1#2#3#4#5#6% 4 skips, post-example skip, L/R equation # code.
  2. {%
  3.      \abovedisplayskip=#1
  4.      \belowdisplayskip=#2
  5.      \abovedisplayshortskip=#3
  6.      \belowdisplayshortskip=#4
  7.      \hfill The Fibonacci numbers are defined\break
  8.      by: $F_0=1$, $F_1=1$, and
  9.      $$F_n = F_{n-1} + F_{n-2} \hbox{, for } n \ge 2.
 10.      \def\temptyF{#6}
 11.      \ifx\temptyF\empty
 12.           \leqno(13.12)$$
 13.      \else
 14.           \eqno(13.12)$$
 15.      \fi
 16.      A related sequence $\{v_n\}$ is: 2, 1, 3, 4, 7, 11, 18, \char144\ It
 17.      satisfies $v_n$ = $x^n + y^n$, where $x = (1 + \sqrt 5)/ 2$
 18.      and $y = (1 - \sqrt 5)/ 2$.
 19.      \vskip#5
 20. }
 21. \tfns{12pt}{12pt}{3pt}{3pt}{1\baselineskip}{}\par
 22. \tfns{12pt}{12pt}{3pt}{3pt}{0pt}{-}
Produces: See typeset version.

Comments:

  • This example is slightly more complicated than the other display skip examples. It uses lines 10-15 to insert an equation number either on the left or on the right of the display.
  • Neither of the displays overlaps the previous line of text. However, the display made by line 21 has a left equation number and uses the regular (non-short) glue. The display made by line 22 has a right equation number and uses short glue.
TeXbook References: 189. Also: 189, 274, 348, 415.

Related Primitives: abovedisplayshortskip, belowdisplayskip.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

belowdisplayskip Math (Glue)
12pt plus 3pt minus 9pt * Parameter (glue)
Synopsis: \belowdisplayskip<glue>

Description:

    AFTER TeX processes a math display, it adds the following items to the current vertical list: a penalty, glue, the actual display, glue, and a penalty. The two glue items are either the above and below displayskips or the above and below displayshortskips. The former are used if: a) the display occurs in the middle of a paragraph and the display overlaps the preceeding line of text; or b) the display has a left equation number [189]. Also, the former are used before and after an alignment display [190].
Example:

     \def\tfn#1#2#3#4#5% above & below regular & short skips + post-example skip
     {%
        \abovedisplayskip=#1
        \belowdisplayskip=#2
        \abovedisplayshortskip=#3
        \belowdisplayshortskip=#4
        The Fibonacci numbers are defined by: $F_0=1$, $F_1=1$, and
        $$F_n = F_{n-1} + F_{n-2} \hbox{, for } n \ge 2.\leqno(13.11)$$
        A related sequence $\{v_n\}$ is: 2, 1, 3, 4, 7, 11, 18, \char144\ It
        satisfies $v_n$ = $x^n + y^n$, where $x = (1 + \sqrt 5)/ 2$
        and $y = (1 - \sqrt 5)/ 2$.
        \vskip#5
     }
     \tfn{3pt}{3pt}{6pt}{6pt}{1\baselineskip}
     \tfn{12pt}{12pt}{6pt}{6pt}{0pt}
Produces: See typeset version.

Comments:

  • This example is similar to the one for \abovedisplayskip. It uses the regular (non-short) display skips.
  • The first example shows what Plain TeX makes if the glue shrinks its maximum amount, and the second example shows what happens if Plain TeX's glue neither stretches nor shrinks.
TeXbook References: 189. Also: 189, 190, 194, 274, 291, 348, 415.

Related Primitives: abovedisplayskip, belowdisplayshortskip.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

binoppenalty Math (Penalties)
700 * Parameter (integer)
Synopsis: \binoppenalty

Description:

    JUST as TeX does not randomly hyphenate words, it does not randomly break math expressions between lines in a paragraph. TeX only considers a break after a relation (e.g., = or <) or a binary operation (e.g., + or ×) [173]. TeX inserts a penalty after a binary operation [174] which is not enclosed in braces and is not part of a generalized fraction [173]. The actual value of the penalty added after a binary operation in an expression is the value of \binoppenalty at the end of the expression [101]. However, the penalty is not inserted if: a) the binary operation is the final item in the entire list; b) the value of the penalty is 10,000 or more; or c) the next item in the list is a penalty item [446-447].
TeXbook References: 174. Also: 101, 174, 272, 322, 348, 446.

Related Primitives: relpenalty.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

botmark Marks
Command
Synopsis: \botmark

Description:

    THIS command holds the mark text that was most recently encountered on the page that was just boxed. It is null (i.e., empty) before the first page. It is equal to the previous \botmark, when a page contains no marks [258]. The value of \botmark is global (i.e., it is not affected by grouping) [259].
Example:

  1. % These lines are from the macro that makes the reference page
  2. % for a control sequence.  See pages 260--261 in TTB for more details.
  3. % We have: \def\CScs{ControlSequence}, e.g., \def\CScs{botmark}
  4. % \box0 holds everything through the Synopsis line.
  5.      \mark{\currentcs\noexpand\else\CScs}
  6. % Do \eject unless following \box0 will fit on current page.
  7. % The \ifdim reference page shows this test.
  8.      \unvbox0%
  9.      \mark{\CScs\noexpand\else\CScs}
 10. % Typeset the rest of the page.
 11.      \let\currentcs=\CScs
Produces: See typeset version.

Comments:

  • It is tricky to get the correct guide word on the header line of these reference pages. Two things are required.
  • First, lines 5 and 9 put a special mark before and after the start of each control sequence. Each mark contains two options separated by `\noexpand\else'.
  • Second, the header routine for recto pages uses `\iftrue\botmark\fi' to select that page's guide word.
  • The `if' statement expands to \currentcs unless the test referred to on lines 6-7 shows there is room for the start of the next command on the current page. If there is, the mark on line 9 appears on the current page, and the `if' statement expands to \CScs.
TeXbook References: 258-260. Also: 213, 258, 259-260, 262-263, 280.

Related Primitives: mark, firstmark, topmark.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

box Box
Command
Synopsis: \box<8-bit register number>

Description:

    THERE are 256 box registers: \box0 to \box255. A \box command adds the contents of the box to the current list, and it empties the box. It often is better to use \unhbox or \unvbox since they remove the outermost layer of glue in the box. That allows the box's contents to mesh with the other items in the current list. The \copy command is similar to \box except \copy does not empty the box [120]. Plain TeX has a \newbox command which reserves a box for a special purpose [121]. Each insertion class (\insert) reserves a box for its use [122]. Also, \box255\mkindexA{box255} holds the current page which is used by the \output routine [253].
Example:

  1. \setbox0=\hbox{\selffamily AB ``Hello, World.''}
  2. \box0\par
  3. \setbox1=\hbox{``You were in a box, but now you are not!''}
  4. \box1\box0
Produces: See typeset version.

Comments:

  • The \box0 command on line 4 does nothing because \box0 was emptied on line 2. See the \copy page for comparison.
TeXbook References: 120-122, 222. Also: 120-122, 151, 222, 278, 346, 354, 386, 387.

Related Primitives: copy, unhbox, unvbox, unhcopy, unvcopy.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

boxmaxdepth Box
\maxdimen or 16383.99998pt * Parameter (dimen)
Synopsis: \boxmaxdepth

Description:

    THIS is a dimen parameter whose Plain TeX value is \maxdimen. It is used to fix the depth and height of vboxes. TeX ensures that the depth of a \vbox is no larger than \boxmaxdepth. If necessary, TeX moves the reference point in the vbox down and thereby increases the height and decreases the depth of the box. When a \vtop is constructed, \boxmaxdepth is not used [81]. An output routine often sets \boxmaxdepth to \maxdepth when it builds the body of each page [255].
Example:

  1. \def\printboxdimensA#1%
  2. {%
  3.      \boxmaxdepth=#1%
  4.      \global\setbox1=\vbox{\hrule height 10pt depth 10pt width 20pt}%
  5.      \the\boxmaxdepth&\the\ht1&\the\dp1&\the\wd1\cr
  6. }
  7. \halign
  8. {\qquad\hfil#&&\quad\hfil#\cr
  9. \bf boxmaxdepth&\bf height&\bf depth&\bf width\cr
 10. \printboxdimensA{0pt}
 11. \printboxdimensA{5pt}
 12. \printboxdimensA{15pt}
 13. \printboxdimensA{\maxdimen}
 14. }
Produces: See typeset version.

Comments:

  • Line 4 makes a \vbox whose dimensions are (10+10)x20.
  • The rows in the table show how the height and depth of the box are related to the value of \boxmaxdepth.
  • Each call to \printboxdimens actually produces one row (line 5) in the table that begins on line 7 and ends on line 14.
TeXbook References: 80-81. Also: 81, 113, 249, 255, 274, 348.

Related Primitives: maxdepth, vbox.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

brokenpenalty Penalties (Page)
100 * Parameter (integer)
Synopsis: \brokenpenalty

Description:

    AFTER TeX breaks a paragraph into lines, it moves each line to the containing vertical list. Normally, TeX places a penalty followed by interline glue between each pair of lines. If a line ends with a discretionary break (e.g., a hyphen), TeX adds \brokenpenalty to the penalties inserted immediately after the line [104].
TeXbook References: 104. Also: 104-105, 272, 348.

Related Primitives: clubpenalty, widowpenalty, interlinepenalty, hyphenpenalty, exhyphenpenalty, discretionary.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

catcode Character
Internal Quantity
Synopsis: \catcode<8-bit number>

Description:

    EACH of the 256 characters TeX may encounter is placed in one of 16 categories numbered 0-15 [37]. The command `\catcode`\{=1' assigns `{' to category 1 [39]. Category codes are changed to get verbatim listings [380].

    Category | Description | Plain TeX Value (Character and ASCII)
0 | Escape character | \ | 92
1 | Beginning of Group | { | 123
2 | End of Group | } | 125
3 | Math shift | $ | 36
4 | Alignment tab | & | 38
5 | End of line | <return> | 13
6 | Parameter | # | 35
7 | Superscript | ^ | 94
8 | Subscript | _ | 95
9 | Ignored character | <null> | 0
10 | Space |  | 32
11 | Letter | A-Z and a-z | 65-90 and 97-122
12 | Other Character | none of above or below
13 | Active Character | ~ | 126
14 | Comment Character | % | 37
15 | Invalid character | <delete> | 127

Example:

  1. \catcode`\?=13 % make ? the special character for in-line verbatim
  2. \def?{\begingroup\ccflip\getword}%
  3. \def\getword#1?{#1\endgroup}%
  4. %
  5. ?\uppercase\expandafter{\romannumeral\year}\par?\par
  6. ?\ { } & $ # ^ _ ~ % Did? you know that
  7. ?\catcode`\{=1? assigns `\{' to category 1\char63
Produces: See typeset version.

Comments:

  • Lines 1-3 should show how easy it is to make TeX do in-line verbatim\mkindex{verbatim} listings.
  • The \ccflip macro changes the catcodes of the special TeX characters listed on line 6 and of the space character. See appendix A for more details.
  • A character other than `?' may be used as the delimiting character provided each `?' on lines 1-3 is changed to the new character.
  • Even though `?' is ASCII 63, TeX did not get confused by `\char63' on line 7.
TeXbook References: 37-39. Also: 39, 134, 214, 271, 305, 343, 380-382, 384, 390-391, 421, 424.

Related Primitives: lccode, sfcode, uccode.

For Additional Examples, see: mathchardef, span

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

char Character
Command
Synopsis: \char<8-bit number>

Description:

    THIS command provides access to all the characters in the current font. The number should be in the range 0-255 [43]. It may be expressed in decimal, octal, hexadecimal, or one of several special TeX formats [44-45]. If \char appears in vertical mode, a new paragraph is started [283]. The command may be used in math mode [289].
Example:

  1. \def\cp{\char152}%       This will trigger an error at some point.
  2. \def\bp{\char131\relax}% Need \relax or `131 }' (with a space).
  3. \cp\ \uppercase\expandafter{\romannumeral\year}\par
  4. At the exchange rate of \bp 1 = \$1.56, \$1000 is \bp 641.03.\par
  5. cp = \meaning\cp\ and bp = \meaning\bp.
Produces: See typeset version.

Comments:

  • Without the \relax (or a space) on line 2, TeX complains (at runtime) about a bad character code (with value 1311) on line 4. This is a variation of a common problem [71]. Note, the \chardef version of this example does not require \relax.
TeXbook References: 43-45. Also: 43-46, 76, 86, 155, 283, 286, 289, 340, 427, 452.

Related Primitives: accent, chardef, mathcode.

For Additional Examples, see: mathchoice

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

chardef Character
Internal Quantity
Synopsis: \chardef<control sequence>=<number>

Description:

    THIS is an efficient alternate to `\def<control sequence>{\char<number>}' [44]. Control sequences defined by \chardef may be used with `\the'. That combination returns <number> in decimal notation [214]. Expansion is suppressed when TeX is reading the <control sequence> [215]. TeX uses hexadecimal notation when it expands `\meaning<control sequence>' [336].
Example:

     \chardef\cp=152
     \chardef\bp=131
     \cp\ \uppercase\expandafter{\romannumeral\year}\par
     At the exchange rate of \bp 1 = \$1.56, \$1000 is \bp 641.03.\par
     cp = \the\cp\ and bp = \meaning\bp.
Produces: See typeset version.

Comments:

  • A comparison of this example with the one for \char shows the version using \def and \char also requires \relax to prevent subtle errors.
TeXbook References: 44. Also: 44, 121, 155, 210, 214, 215, 271, 277, 336, 343, 345, 356, 452.

Related Primitives: char, def.

For Additional Examples, see: meaning

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

cleaders Box
Command
Synopsis: \cleaders<box or rule><glue>

Description:

    LEADERS are used to fill space with a box or a rule. Normally, copies of a box will not completely fill a specified space. So, in addition to \leaders, TeX provides two additional ways to put boxes in the space. The first is \cleaders. It packs boxes tightly together and centers them in the specified space. The second is \xleaders. It breaks the leftover space into equal pieces and puts one piece between each box and on the left and right ends of the boxes. The result is an sbsb \char144\ sbs pattern where s stands for one of the pieces of space and b for one of the boxes [224].
Example:

  1. \def\sampletocA#1#2%
  2. {%
  3.      \setbox0=\hbox to 25pt{\vrule height 0.4pt depth 0pt width 25pt}
  4.      \setbox1=\hbox to 25pt{\vrule\hfil #2}% coincidence that both boxes use 25.
  5.      \vbox
  6.      {
  7.           \hsize=224pt% 24 pt left over!
  8.           #1\vrule\leaders\copy0\hfill\copy1\par
  9.           #1\vrule\cleaders\copy0\hfill\copy1\par
 10.           #1\vrule\xleaders\copy0\hfill\copy1\par
 11.      }
 12. }
 13. \sampletocA{\noindent}{100}
 14. \sampletocA{Strangers and Brothers}{116}
 15. \sampletocA{The Age of Reason}{178}
Produces: See typeset version.

Comments:

  • The \vrule on line 8 prevents the \leaders for page 100 from beginning at the left margin.
  • If the three vboxes made by the three \sampletocA calls appear too close together, they are! One way to avoid this problem is to use struts [82].
TeXbook References: 224. Also: 224, 225-226, 357, 374.

Related Primitives: leaders, xleaders.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

closein File I/O
Command
Synopsis: \closein<4-bit number>

Description:

    THIS command is used to close a file previously opened by \openin. The number used with \closein should be in the range 0-15 and be the same number used with \openin [217].
Example:

  1. \def\tfn{junkjunk.tex}
  2. \openin\traux=\tfn\relax
  3. \ifeof\traux
  4.      \closein\traux
  5. \else
  6.      \closein\traux
  7.      \input\tfn\relax
  8. \fi
Produces: See typeset version.

Comments:

  • The junkjunk.tex file doesn't hold anything useful, but the lines illustrate one way to read an auxilary file. Note the use of \relax on line 2.
  • The junkjunk.tex file is made by the example on the \closeout reference page.
TeXbook References: 217. Also: 217, 280.

Related Primitives: openin, read.

For Additional Examples, see: openin

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

closeout File I/O
Command
Synopsis: \closeout<4-bit number>

Description:

    THIS command is used to close a file previously opened by \openout. The number used with \closeout should be in the range 0-15 and be the same number used with \openout [226]. Unless the command is preceeded by \immediate, TeX places the command in a whatsit\mkindex{whatsit`5`file I/O} item in the current list and delays closing the file until a \shipout encounters the list [227].
Example:

     \openout\twaux=junkjunk.tex\relax
     \write\twaux{{\noexpand\bf byebye}\ World}
     \closeout\twaux
Produces: See typeset version.

Comments:

  • This example produces no visible output. However, the example on the \closein reference page uses junkjunk.tex. Note, byebye shows up in bold.
  • Actually, the \immediate reference page explains how junkjunk.tex is really made.
TeXbook References: 226-228. Also: 226-228, 254, 280, 422.

Related Primitives: openout, write, immediate.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

clubpenalty Penalties (Page)
150 * Parameter (integer)
Synopsis: \clubpenalty

Description:

    AFTER TeX breaks a paragraph into lines, it moves each line to the containing vertical list. Normally, TeX places a penalty followed by interline glue between each pair of lines. TeX adds \clubpenalty to the penalties inserted immediately after the first line in the paragraph [104].
TeXbook References: 104. Also: 104, 113, 272, 317, 348, 419.

Related Primitives: widowpenalty, brokenpenalty, interlinepenalty.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

copy Box
Command
Synopsis: \copy<8-bit register number>

Description:

    THIS command add a copy of the list in the box register to the current list. It behaves just like the \box command except it does not change the contents of the register [120].
Example:

  1. \setbox0=\hbox{\selffamily AB ``Hello, World.''}
  2. \copy0\par
  3. \setbox1=\hbox{``Are you still in a box?''}
  4. \copy1\copy0
Produces: See typeset version.

Comments:

  • The \copy0 command on line 4 produces the second ``Hello World'' line. See the \box reference page for comparison.
  • Even though line 4 makes it look as if \box0 and \box1 will appear on the same line, they don't. That is because in vertical mode boxes are stacked on top of each other.
TeXbook References: 120, 222. Also: 120, 151, 222, 278, 329, 374, 386, 407.

Related Primitives: box, unhcopy, unvcopy.

For Additional Examples, see: cleaders, unhbox

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

count Registers
Internal Quantity
Synopsis: \count<8-bit register number>=<number>

Description:

    THERE are 256 count registers: \count0 to \count255. Each may hold an integer from -2,147,483,647 to 2,147,483,647 (i.e., from -231 to 231). The commands \advance, \multiply, and \divide allow limited arithemetic with the registers [118]. TeX considers \count0 to \count9 to be special and writes the nonzero ones to the terminal and log file each time it writes a page [119]. Plain TeX uses \count0 to hold the page number [119, 362]. The count registers obey TeX's grouping structure. So, changes to a register inside a group will not affect the value of the register outside the group unless \global is used with the register [119]. The command \showthe\count n writes the value for \count n to the terminal and to the log file [121]. The register \count255 is available for temporary storage [122].
Example:

  1. \count1 = 100
  2. \count2=\count1
  3. \multiply\count2 by 3
  4. \divide\count2 by 2
  5. %\count2=1.5\count1% This does not work with count registers.
  6. The counts are: \the\count1, \the\count2.
Produces: See typeset version.

Comments:

  • Compare this example which tries to multiply a count register by 1.5 with the example on the \dimen reference page. On that page the technique shown on line 5 works.
TeXbook References: 118-122. Also: 118-122, 207-208, 271, 276, 346-347, 379.

Related Primitives: countdef, ifodd, ifnum, advance, multiply, divide.

For Additional Examples, see: advance, day, divide, ifnum, time, year

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

countdef Registers
Command
Synopsis: \countdef<name>=<8-bit register number>

Description:

    A count register may be used directly (e.g., \count21=1) [118] or indirectly in one of two ways. Each indirect way involves setting up a symbolic name for a register (e.g., \sectno for section number). The first indirect way uses the primitive \countdef (e.g., `\countdef\sectno=21'); this makes \sectno equivalent to \count21. So, the command `\sectno=1' sets the section number to 1 [119]. The second indirect way uses the Plain TeX command \newcount (e.g., `\newcount\sectno'). This time the control sequence \sectno is a count register, but it is not at all apparent which one (the log file should contain a line `\sectno=\count n' for some n) [121]. The direct method is fine for registers used locally in a macro or in a group. The \newcount method (or something equivalent if Plain TeX is not used) is the preferable indirect method. If macros from several sources are used, and two different \countdef's use the same register number, the macros may interfere with each other. This type of problem is difficult to track down [nr]. TeX suppresses expansion when it is reading a control sequence that will be defined by a \countdef [215].
Example:

     % count registers
     \newcount\headnum\headnum=0 %       0-2: see \def\makeheadline{}.
     \newcount\linenumber\linenumber=0 % puts lines # on :exam and :logf data.
     \newcount\notenumber\notenumber=0 % numbers \trC{} items.
Produces: See typeset version.

Comments:

  • These lines are from the start of the macro file used to prepare these pages and setup needed \count registers. Note, each register is initialized after it is created.
TeXbook References: 119. Also: 119, 121, 210, 215, 271, 277, 346-347.

Related Primitives: count.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

cr Tables
Command
Synopsis: \cr

Description:

    THIS command is placed at the end of the preamble of an \halign and at the end of each row of data in the \halign [235]. If a particular row in a table requires fewer columns than was specified in the preamble, a \cr after the last one tells TeX: ``there are no more columns on this line'' [245]. When used with a \valign, \cr marks the bottom of a column [249]. Tokens specified by \everycr are inserted after every \cr [275].
Example:

  1. \def\tf#1{\omit\hfil #1\hfil}
  2. \vbox{\halign
  3. {#\hfil\quad&\quad\hfil#\quad&\quad\hfil#\quad&\quad\hfil#\cr
  4. \multispan4\hfil 1970 Federal Budget Transfers\hfil\cr
  5. \multispan4\hfil (in billions of dollars)\hfil\cr
  6. \tf{State}&\tf{Taxes}&\tf{Money}&\tf{Net}\cr
  7. &\tf{collected}&\tf{Spent}\cr
  8. New York&   22.91& 21.35& -1.56\cr
  9. New Jersey&  8.33&  6.96& -1.37\cr
 10. Connecticut& 4.12&  3.10& -1.02\cr
 11. Maine&       0.74&  0.67& -0.07\cr
 12. California& 22.29& 22.42& +0.13\cr
 13. New Mexico&  0.70&  1.49& +0.79\cr
 14. Georgia&     3.30&  4.28& +0.98\cr
 15. Mississippi& 1.15&  2.32& +1.17\cr
 16. Texas&       9.33& 11.13& +1.80\cr
 17. }}
Produces: See typeset version.

Comments:

  • This example begins a multi-reference page example of a table.
  • The first version is quite simple. All it does is enter the text of the table. Subsequent versions will add vertical and horizontal rules and polish.
  • Note \tf which is defined on line 1 and used on lines 6-7.
  • The final version of the table is on the \halign reference page, and the next version is on the \omit reference page.
TeXbook References: 231, 235-236. Also: 175-177, 190-197, 231-238, 245, 248, 275, 282, 351-352, 385-386, 412, 418, 421.

Related Primitives: crcr, everycr, halign, valign.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

crcr Tables
Command
Synopsis: \crcr

Description:

    THIS commands acts like \cr unless it immediately follows a \cr or a \noalign in which case it does nothing [249]. The command often appears in a macro used to format a table (e.g., Plain TeX's \matrix or \cases) [361-362]. Tokens specified by \everycr are inserted after every nonredundant \crcr [275].
Example:

  1. \def\er{\crcr\noalign{\hrule}}%                   \cr\cr makes a blank line
  2. \def\strutA#1#2{\vrule height#1 depth#2 width0pt}%\cr\crcr DOES NOT !
  3. \def\tm{\hskip0.5em}
  4. \halign
  5. {\strutA{8.5pt}{3.5pt}\vrule#&\tm#\hfil\tm&\tm#\hfil\tm&\tm#\hfil\tm&
  6. #\vrule\cr\er
  7. \strutA{9.5pt}{3.5pt}&january&february&march&\cr
  8. &april&may&\multispan2\vrule height3.5pt depth 3.5pt
  9.  \leaders\hrule height3.5pt depth-3.1pt\hfill\vrule\cr
 10. &june&july&\omit\vrule\tm\bf Months\hfil&\cr
 11. &august&september&\multispan2\vrule height8.5pt depth-3.0pt
 12.  \leaders\hrule height3.4pt depth-3.0pt\hfill\vrule\cr
 13. &october&november&december&\er
 14. }
Produces: See typeset version.

Comments:

  • The \er macro (defined on line 1) is used instead of \cr when a horizontal rule the width of the table is needed.
  • The Months table only requires \er twice: before the first data row (i.e., at the end of the preamble) and after the last data row.
  • The preamble has to end with a \cr, and the use of \crcr (instead of just \cr) in \er prevents the table from starting with a blank line.
  • Also, notice the trick used on lines 8-9 and 11-12 to position the horizontal and vertical rules around `Months'. That trick and a similar one used on the \span reference page should make it possible to put rules at any position in a table.
  • The table is from ``Tbl-A Program to Format Tables'' by M. E. Lesk, which in turn begins on page 157 of Unix Programmer's Manual, Volume 2, 1983.
TeXbook References: 249. Also: 249, 275, 282, 361-362, 385, 412, 421.

Related Primitives: cr, everycr.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

csname Macro
Command
Synopsis: \csname<tokens>\endcsname

Description:

    A \csname token must be followed by a matching \endcsname token. TeX expands each of the intervening <tokens>. If only character tokens are made, TeX forms a control sequence using all the characters, but, if the expansion produces a primitive, TeX reports an error [40]. If the newly formed control sequence is currently undefined, it is defined to be like \relax [213]. The commands (\csname and \endcsname) allow a document or formatting routine to build a control sequence token on the fly [nr].
Example:

  1. \def\tmakedef#1#2{\expandafter\xdef\csname #1\endcsname{#2}}%
  2. \count1=0
  3. \def\mkr#1#2%
  4. {%
  5.      \global\advance\count1 by 1
  6.      \tmakedef{ref#1count}{\the\count1}%
  7.      \tmakedef{ref#1desc}{#2}%
  8. }
  9. \mkr{A}{The Big Picture}
 10. \mkr{B}{Tons of Details}
 11. \mkr{C}{The Final Hour}
 12. \global\count1=0
 13. B---\refBcount---\refBdesc
Produces: See typeset version.

Comments:

  • This example has three parts: lines 1-8 which would normally be in a formatting file; lines 9-11 which would normally appear at random places in a document; and lines 12-13 which perform cleanup and check things work.
  • Line 1 holds a general purpose macro which builds a control sequence using parameter 1 and defines a macro for the new control sequence which returns parameter 2. The macro uses \xdef to define each new macro instead of the more familar \def. This means each new macro is global and the replacement text (i.e., the value of \count1 on line 6) is expanded when the macro is made (e.g., on line 10) instead of when it is used (e.g., on line 13). The new macro needs to be global because each Example actually takes place inside a group which normally prevents changes made in the example from interfering with the rest of the document.
  • Lines 3-8 form a link between \tmakedef and a document. The macro \mkr advances a counter and makes two new control sequences: the first holds the counter and the second holds descriptive text.
  • Lines 9-11 make three calls to \mkr. This results in six new control sequences.
  • Line 12 is needed to reset \count1. In actual practice a dedicated counter (obtained via \newcount) would be used instead of count1.
  • Finally, line 13 checks things work. However, a much better check is shown on the \endcsname reference page.
TeXbook References: 40, 213. Also: 40-41, 213, 348, 375.

Related Primitives: endcsname.

For Additional Examples, see: noexpand, the

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

day Job
Parameter (integer)
Synopsis: \day

Description:

    AT the beginning of each job TeX sets this parameter to the current day (1-31) in the month [349].
Example:

  1. \def\mkordinal#1% convert 2 digit integer (1-99) to ordinal: 1st, 2nd, ...
  2. {%
  3.   {%
  4.      \count1=#1
  5. %     \the\count1-
  6.      \divide\count1 by 10 % makes most significant digit.
  7. %     \the\count1-
  8.      \count3=\count1
  9.      \multiply\count3 by 10
 10.      \count2=#1
 11.      \advance\count2 by -\count3 % makes least significant digit.
 12.      \ifcase\count2\def\tss{th}% 10th, 20th, 30th.
 13.      \or \def\tss{st}%   1st
 14.      \or \def\tss{nd}%   2nd
 15.      \or \def\tss{rd}%   3rd
 16.      \else \def\tss{th}% xth
 17.      \fi
 18.      \ifnum\count1=1 %  adjust for 11, 12, 13.
 19.           \def\tss{th}%
 20.      \fi
 21. %     \the\count2--
 22.      #1\superscript{\tss}%
 23.   }%
 24. }
 25. \mkordinal{1},  \mkordinal{2},  \mkordinal{3},  \mkordinal{4},
 26. \mkordinal{11}, \mkordinal{12}, \mkordinal{13}, \mkordinal{14},
 27. \mkordinal{21}, \mkordinal{22}, \mkordinal{23}, \mkordinal{24}, and
 28. \mkordinal{31}.\par
 29. Today is the \mkordinal{\the\day} day of the month.
Produces: See typeset version.

Comments:

  • The purpose of the macro is to produce something similar to what line 29 makes.
  • The first version of this macro did not work. Lines 5, 7, and 21 were added to try and see where things were going wrong. It turned out that line 6 did not have the space after 10 and before the comment (i.e., it was `10%'). The moral is: ``a number often needs a space or \relax after it.''
TeXbook References: 349. Also: 273, 349, 406.

Related Primitives: month, year, time.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

deadcycles Job
Internal Quantity
Synopsis: \deadcycles

Description:

    THIS holds the number of times the output routine was performed since the last \shipout. It is set to zero after every \shipout, and it is increased by 1 just before every \output [255].
TeXbook References: 255. Also: 214, 255, 264, 271, 283, 401.

Related Primitives: maxdeadcycles, output, shipout, end.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

def Macro
Command
Synopsis: \def<control sequence><parameter text>{<replacement text>}

Description:

    THIS command is used to define a macro. TeX stores the definition (replacement text) and expands the macro when it encounters the macro's control sequence in a document [199-203]. If \par occurs in one of the parameters of a macro, TeX stops processing and reports a runaway argument unless the macro was declared \long [205]. A macro defined inside a group is local to that group unless the macro was declared \global. A macro may be declared \outer if the macro should not be allowed in: a) the argument, the parameter text, or the replacement of another macro; b) the preamble of an alignment; or c) conditional text. The three prefixes (\long, \global, and \outer) can be applied to \def in any order, and they can appear more than once [206].
Example:

  1. \def\ta{Bye}
  2. \def\tb{Bye}
  3. 1. \ta\tb.\par
  4. \begingroup
  5. \def\ta{Hello}
  6. \def\tb{ World}
  7. 2. \ta\tb.\par
  8. \endgroup
  9. 3. \ta\tb.\par
Produces: See typeset version.

Comments:

  • This example illustrates the local nature of a macro's definition.
  • Lines 1-3 define two macros and typeset each of them.
  • Lines 4-8 hold a new group and contain new definitions for the two macros.
  • Line 9 typesets the macros a third time. The results are the same as the first time since lines 3 and 9 are in the same group, and no redefinitions occurred in that group.
TeXbook References: 203-206. Also: 44, 136, 199-208, 215, 275-276.

Related Primitives: gdef, edef, xdef, global, long, outer, chardef, mathchardef, countdef, dimendef, muskipdef, skipdef, toksdef.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

defaulthyphenchar Hyphenation
45 (`- = 45) * Parameter (integer)
Synopsis: \defaulthyphenchar=<number>

Description:

    WHEN TeX loads a new font, it sets the \hyphenchar of the font to this value [273]. The Plain TeX value is 45 which is the ASCII value of a hyphen `-' [348]. Once a font is loaded, a new assignment may be made. For example, the manmac format sets `\hyphenchar \tentt=-1' [414]. This prevents hyphenation of the control sequence names and keywords which appear in The TeXbook [454]. Setting `\defaulthyphenchar=-1' at the top of a document disables hyphenation for the document [nr].
TeXbook References: 273. Also: 273, 348, 414, 454.

Related Primitives: hyphenchar.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

defaultskewchar Math (Character)
-1 * Parameter (integer)
Synopsis: \defaultskewchar

Description:

    EACH time TeX loads a new font, it sets the \skewchar of the font to this parameter. Since most fonts do not have or need a working skew char, there is little need to change this parameter from its Plain TeX value [273].
TeXbook References: 273. Also: 273, 348.

Related Primitives: skewchar.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

delcode Math (Character)
Internal Quantity
Synopsis: \delcode<8-bit number>=<24-bit number>

Description:

    EACH of the 256 characters TeX works with has a \delcode. INITEX sets all delcodes to -1 except the one for a `.' which it makes 0 [345]. Only characters which can act as delimiters in math formulas require a positive delcode. A delcode assignment looks like: `\delcode`a="uvwxyz '. It means a small form of the delimiter for the character a has position "vw in family "u, and a large form has position "yz in family "x. If either form is in position 0 of family 0, the form is ignored. TeX only looks at the delcode of a character when the character follows \left, \right, or one of the `..withdelims' commands. If the delcode of the character is negative, TeX reports an error. Otherwise, it uses the value to decide on the size delimiter to use. The above rules explain why `\right.' does not make a delimiter [156]. Plain TeX makes nine assignments similar to `\delcode`\[="05B302 '. This one makes [ an acceptable delimiter. Also, it says a small form of the delimiter is in position "5B of family 0 and a large version is in position "02 of family 3 [345, 427, and 432].
TeXbook References: 156, 345. Also: 156, 214, 271, 290, 345.

Related Primitives: mathcode, delimiter, fam.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

delimiter Math (Character)
Command
Synopsis: \delimiter<number>

Description:

    THIS command provides a way to specify a delimiter directly. The number should be seven hexadecimal digits. Its leading digit must be in the range 0-7. That digit functions as a class number, and the remaining six digits function as a \delcode value [156]. Plain TeX has over twenty definitions similar to: `\def\rceil{\delimiter"5265307 }' [359]. This definition means \rceil is in family 5 (closing), its small form is in family 2 position "65, and its large form is in family 3 position "07. A \delimiter specifies a math symbol and works in two ways. When TeX is looking for a delimiter (e.g., after \left), it ignores the class digit and uses the remaining six digits as a \delcode. But, when the delimiter appears in other contexts, the right three digits are dropped, and the remaining four digits become the symbol's \mathcode. For \rceil that means the \delcode is "265307 and the \mathcode is "5265 [156].
Example:

  1. \def\tdela{\delimiter"462833A }% a space or \relax is mandatory!
  2. \def\tdelb{\delimiter"562933B }
  3. \setbox0=\vbox{\hsize=2in$\tdela x-y\tdelb(x+y)=x^2-y^2$}
  4. \def\tbox#1#2#3%
  5. {%
  6.      \setbox#1=\vbox{\hsize=1.5in$$#2\sum_{n=0}^\infty {1\over2^n}#3^2 = 4$$}
  7. }
  8. \tbox1{\tdela}{\tdelb}
  9. \tbox2{\left\tdela}{\right\tdelb}
 10. \hbox to \hsize{\quad\raise24pt\box0\hfil\raise4pt\box1\hfil\box2\quad}
Produces: See typeset version.

Comments:

  • Lines 1-2 define two control sequences: \tdela and \tdelb. Plain TeX calls them: \lgroup and \rgroup [359].
  • On lines 3 and 8 TeX treats the new items as ordinary math symbols whose mathcodes are: "4628 and "5629. Plain TeX's family 6 is cmbx [157], and the characters in positions "28 and "29 of it are bold forms of the left and right parenthesis.
  • On line 9 TeX treats the new items as delimiters. The display requires the large form of each delimiter, so "33A and "33B are used. Those characters are in family 3, the math extension font.
TeXbook References: 156. Also: 156, 289-290, 359.

Related Primitives: mathcode, delcode, fam, radical.

For Additional Examples, see: nulldelimiterspace

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

delimiterfactor Math
901 * Parameter (integer)
Synopsis: \delimiterfactor

Description:

    WHEN TeX computes the size of delimiters for a `\left<subformula>\right' construction, it begins by calculating the distances the subformula extends above and below the axis. Next, it makes y equal to twice the maximum of the distances just computed. Then, it computes `y·f/1000' and `y-d'. Finally, it makes the actual delimiters larger than each of the last two calculations. In the calculations f is the \delimiterfactor and d is the \delimitershortfall [152].
Example:

  1. \def\tf#1#2%
  2. {%
  3.    $$\delimiterfactor=#1
  4.      \delimitershortfall=#2
  5.      f(x) = \left\{\vcenter{%
  6.      \halign
  7.      {$##\hfil$&\quad ##\hfil\cr
  8.           x^2 + 2x - 1  & if $x < 0$,\cr
  9.           x^3 - 1       & if $0 \le x < 1$,\cr
 10.           x^2 + x - 1   & if $1 \le x < 2$,\cr
 11.           x^3 - x^2 + 1 & if $2 \le x$.\cr
 12.      }}%
 13.      \right.% NO right delimiter!
 14.    $$%
 15. }
 16. \setbox0 = \vbox{\hsize=2.25in\tf{901}{5pt}}
 17. \setbox1 = \vbox{\hsize=2.25in\tf{500}{\maxdimen}}
 18. \hbox to 5.0in{\quad\box0\hfill\box1}
Produces: See typeset version.

Comments:

  • Lines 1-15 define a macro with two parameters. Line 3 sets \delimiterfactor to the first parameter, and line 4 sets \delimitershortfall to the second parameter. The remaining lines construct a multi-line function and use \left to make the left brace in that construction.
  • Line 16 calls the macro using Plain TeX's values for the two parameters.
  • Line 17 uses values that cause TeX to ignore \delimitershortfall and to use a scaling factor of ½.
  • Line 18 typesets each of the boxes made by lines 16-17.
TeXbook References: 152. Also: 152, 273, 348, 446.

Related Primitives: delimitershortfall, left, right.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

delimitershortfall Math
5pt * Parameter (dimen)
Synopsis: \delimitershortfall

Description:

    WHEN TeX computes the size of delimiters for a `\left<subformula>\right' construction, it begins by calculating the distances the subformula extends above and below the axis. Next, it makes y equal to twice the maximum of the distances just computed. Then, it computes `y·f/1000' and `y-d'. Finally, it makes the actual delimiters larger than each of the last two calculations. In the calculations f is the \delimiterfactor and d is the \delimitershortfall [152].
Example:

  1. \setbox0 = \vbox{\hsize=2.25in\tf{901}{5pt}}
  2. \setbox1 = \vbox{\hsize=2.25in\tf{10}{12pt}}
  3. \hbox to 5.0in{\quad\box0\hfill\box1}
Produces: See typeset version.

Comments:

  • This example should be compared to the one on the \delimiterfactor reference page. In particular, that page contains the definition of the macro \tf.
  • Line 1 calls the macro using Plain TeX's values for \delimiterfactor and \delimitershortfall.
  • Line 2 uses values that cause TeX to ignore \delimiterfactor and to make the brace about one line smaller than it should be.
TeXbook References: 152. Also: 152, 274, 348, 446.

Related Primitives: delimiterfactor, left, right.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

dimen Registers
Internal Quantity
Synopsis: \dimen<8-bit register number>=<dimen>

Description:

    THERE are 256 dimen registers: \dimen0 to \dimen255. Each may hold a dimension. The commands \advance, \multiply, and \divide allow limited arithemetic with the registers. A dimen register may be placed in a count register. TeX converts a dimension to a number by assuming units of sp (scaled points) [118]. The dimen registers obey TeX's grouping structure. So, changes to a register inside a group will not affect the value of the register outside the group unless \global is used with the register [119]. The command `\showthe\dimen n' writes the value for `\dimen n' to the terminal and to the log file [121]. The register \dimen255 is available for temporary storage [122].
Example:

  1. \dimen1=10pt
  2. \dimen2=1.5\dimen1
  3. \dimen3=-\dimen2
  4. \dimen4=0.66667\dimen3
  5. The dimens are: \the\dimen1, \the\dimen2, \the\dimen3, \the\dimen4.\par
  6. \dimen1=1pt
  7. \dimen2=1sp
  8. \count1=\dimen1
  9. \count2=\dimen2
 10. The counts are: \the\count1, \the\count2.\par
Produces: See typeset version.

Comments:

  • Lines 1-4 show how easy it is to set one \dimen register equal to a fractional multiple of another register.
  • Lines 6-9 show how \dimen registers are converted to \count registers.
TeXbook References: 118-119. Also: 118-122, 271, 276, 346-347, 349, 360, 363, 395.

Related Primitives: dimendef, ifdim, advance, multiply, divide, count.

For Additional Examples, see: divide, prevdepth

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

dimendef Registers
Command
Synopsis: \dimendef<name>=<8-bit register number>

Description:

    A dimen register may be used directly (e.g., \dimen17=\hsize) [118] or indirectly in one of two ways. Each indirect way involves setting up a symbolic name for a register (e.g., \pagewidthA). The first indirect way uses the primitive \dimendef (e.g., `\dimendef\pagewidthA=17'); this makes \pagewidthA equivalent to \dimen17. So, the command `\pagewidthA=\hsize' stores a copy of \hsize [119]. The second indirect way uses the Plain TeX command \newdimen (e.g., `\newdimen\pagewidthA'). This time the control sequence \pagewidthA is a dimen register, but it is not at all apparent which one. The log file should contain a line `\pagewidthA=\dimen n' for some n [121]. The direct method is fine for registers used locally in a macro or in a group. The \newdimen method or something equivalent if Plain TeX is not used is the preferable indirect method. If macros from several sources are used, and two different \dimendef's use the same register number, the macros may interfere with each other. This type of problem is difficult to track down [nr]. TeX suppresses expansion when it is reading a control sequence that will be defined by a \dimendef [215].
Example:

     % dimen registers
     \newdimen\pagewidthB     % width of regular output, don't change.
     \newdimen\pagewidthA     % page width, may change.
     \newdimen\pageheightB    % permanent page height, vsize changes in doublecolumn
     \newdimen\parindentA     % alternate parindent.
     \pagewidthB=\hsize
     \pagewidthA=\hsize
     \pageheightB=\vsize
     \parindentA=1.5pc
     \parindent=0pt
Produces: See typeset version.

Comments:

  • These lines are from the start of the macro file used to prepare these pages and setup needed \dimen registers. Note, each register is initialized after it is created.
TeXbook References: 119. Also: 119, 215, 277, 346-347.

Related Primitives: dimen.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

discretionary Hyphenation
Command
Synopsis: \discretionary{<pre-break text>}{<post-break text>}{<no-break text>}

Description:

    A discretionary break consists of three sequences of characters: the pre-break, post-break, and no-break text. This command makes it possible to insert a discretionary break at any point in a paragraph [95]. Discretionary breaks are important because they are one of the five places where TeX breaks lines when it is making paragraphs [96]. If this command occurs in one of the vertical modes, it starts a new paragraph [283]. In math mode the no-break text must produce an empty list [292]. The text should contain only characters, ligatures, kerns, boxes, and rules. It should not have penalties or glue. The space factor is not changed after a discretionary [287]. In unrestricted horizontal mode a \discretionary{}{}{} is added after a character whose code is the \hyphenchar of its font (e.g., `-') and after a ligature formed from a sequence which ends with such a character (e.g., an endash or emdash) [286].
Example:

  1. \def\tstoryA{There are cries, sobs, confusion among the people, and at
  2. that moment the cardinal himself, the Grand Inquisitor, passes by the
  3. cathedral. He is an old man . . .}
  4. \def\tstoryB{There are cries, sobs, confusion among the people, and at
  5. that m\discretionary{om-}{e}{ome}nt the cardinal himself, the Grand
  6. Inquisitor, passes by the cathedral. He is an old man . . .}
  7. \setbox0=\vbox{\hsize=2.25in \tstoryA}
  8. \setbox1=\vbox{\hsize=2.25in \tstoryB}
  9. \hbox to \hsize{\box0\hfill\box1}
Produces: See typeset version.

Comments:

  • Line 5 uses \discretionary to hyphenate `moment' as: `mom-ent'.
TeXbook References: 95-96. Also: 95-96, 283, 286, 287, 292.

Related Primitives: -, hyphenchar, hyphenation.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

displayindent Math (Paragraph)
Parameter (dimen)
Synopsis: \displayindent

Description:

    WHEN TeX reads the opening $$ of a math display, it sets \displayindent to the amount of indentation for the current line. Normally, that value is 0 pt, but it depends on the paragraph shape specified by \parshape and on hanging indentation. In the latter two cases TeX figures the indentation using line 1 if the display begins the paragraph or line `\prevgraf+2' if the display occurs after \prevgraf lines. TeX uses \displayindent in deciding how much glue to put before and after the display and where to position the display on its line. The parameter may be changed inside a display, and TeX uses the last value it encounters in the display [189]. Each row in an alignment display is shifted right by this parameter [190].
Example:

  1. \def\tfn#1#2#3%
  2. {%
  3.    \hangafter=-6 % lines 1-6 are shortened.
  4.    \hangindent=#1
  5.    The Fibonacci numbers are defined by: $F_0=1$, $F_1=1$, and
  6.    $$
  7.      F_n = F_{n-1} + F_{n-2} \hbox{, for } n \ge 2.\eqno(#2.)
  8.      \global\setbox#2=\hbox{(#2.) is \the\displayindent}
  9.    $$
 10.    A related sequence $\{v_n\}$ is: 2, 1, 3, 4, 7, 11, 18, \char144\ It
 11.    satisfies $v_n$ = $x^n + y^n$, where $x = (1 + \sqrt 5)/ 2$
 12.    and $y = (1 - \sqrt 5)/ 2$.
 13.    \vskip#3
 14. }
 15. \tfn{-144pt}{1}{1\baselineskip}
 16. \tfn{144pt}{2}{0.25\baselineskip}
 17. \hbox{The indent for \box1\ and for \box2.}
Produces: See typeset version.

Comments:

  • This example typesets a paragraph containing a math display and hanging indentation. The material is typeset first with the indent on the right and then with it on the left. In each case the value for \displayindent (typeset by lines 8 and 17) is the amount the line needs to be shifted.
  • TeX assumes each display and alignment display takes three lines: a blank line, the actual expression, and a blank line [188, 190]. That explains why the value of \hangafter given on line 3 only shortens three lines of text plus the display.
TeXbook References: 188. Also: 188, 190, 274, 291, 349.

Related Primitives: displaywidth, predisplaysize, abovedisplayskip, prevgraf.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

displaylimits Math
Command
Synopsis: \displaylimits

Description:

    SEVERAL math symbols such as summation and integration often appear with subformulas as subscripts and superscripts. The subformulas may be typeset either above and below or to the right of the symbol. Normal mathematical conventions use the first method for most displayed expressions and the second for most in-line expressions. TeX's conventions use the first method in display style and the second method in text style. TeX has three commands which change these conventions: \limits always uses the first method; \nolimits always uses the second method; and \displaylimits uses TeX's normal conventions. If two or more of these commands follow each other, the last one controls how the expression is typeset [144]. Each of these commands must follow a large operator (class 1). Otherwise, TeX generates an error [292].
Example:

  1. \mathchardef\Intop="1352
  2. \mathchardef\Sum="1350
  3. \def\tint{\Intop\nolimits}
  4. \def\tsum{\Sum}
  5. \def\tf#1#2#3%
  6. {%
  7.      $$\hbox{$#2_0^1 3x^2 = x^3]_0^1 = 1$}%
  8.           \hbox{ and $#3^\infty_{n=0}{1\over2^n} = 2$}%
  9.           \kern2pc
 10.           #2_0^1 3x^2 = x^3\Bigr]_0^1 = 1
 11.           \kern2pc
 12.           #3^\infty_{n=0}{1\over2^n} = 2
 13.           \kern2pc
 14.           \leqno{#1.}
 15.      $$
 16. }
 17. \tf 1{\tint}{\tsum}
 18. \tf 2{\tint\displaylimits}{\tsum\displaylimits}
Produces: See typeset version.

Comments:

  • Lines 1-4 are adapted from Plain TeX [358]. They setup symbols for summation and integration. The integral symbol includes \nolimits because that is how integrals normally appear.
  • Lines 5-16 define a macro which mixes in-line math with display math.
  • Line 17 calls \tf using \tint and \tsum. This typesets each expression as it was intended to be typeset.
  • Line 18 makes a similar call only each symbol is followed by \displaylimits. This changes the form of the third expression.
  • I tried the `]' on line 10 in two ways (see the \nolimits reference page for the second way) but prefer the way shown here.
TeXbook References: 144. Also: 144, 159, 292, 443.

Related Primitives: limits, nolimits, textstyle, displaystyle.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

displaystyle Math
Command
Synopsis: \displaystyle

Description:

    THIS command is used to specify display style. TeX uses four main styles to typeset formulas and subformulas: display, text, script, and scriptscript. Each main style has a corresponding cramped style. The eight styles are referred to as: D, D', T, T', S, S', SS, and SS' where the primed letter means the cramped style. TeX uses the text font (\textfont) for the current family (\fam) when it typesets material in display and text styles (both regular and cramped) [140]. The body of the following table lists the style of the major components in a formula whose style is known:
    component in formula | current style of formula
 | D | D' | T | T' | S, SS | S', SS'
superscript | S | S' | S | S' | SS | SS'
subscript | S' | S' | S' | S' | SS' | SS'
numerator | T | T' | S | S' | SS | SS'
denominator | T' | T' | S' | S' | SS' | SS'
    Finally, most math commands including \underline do not change the current style, but \overline, \sqrt, and math accents change regular styles to cramped ones [141].
Example:

  1. \def\mkcstyle#1#2%
  2. {%
  3.      \vbox to 0pt
  4.      {%
  5.           \vss
  6.           \hbox{$#1{\atop #2^2}$}%
  7.           \kern0pt
  8.      }%
  9. }
 10. \halign{#\hfil&&\quad#\hfil\cr
 11. \it D&\it T&\it D\ftB, T\ftB&\it S&\it S\ftB&\it SS&\it SS\ftB\cr
 12. \noalign{\vskip2pt\hrule\vskip3pt}
 13. $\displaystyle x^2$&$x^2$&\mkcstyle{\displaystyle}{x}&
 14. $\scriptstyle x^2$&\mkcstyle{\textstyle}{x}&
 15. $\scriptscriptstyle x^2$&\mkcstyle{\scriptstyle}{x}\cr
 16. $\displaystyle X^2$&$X^2$&\mkcstyle{\displaystyle}{X}&
 17. $\scriptstyle X^2$&\mkcstyle{\textstyle}{X}&
 18. $\scriptscriptstyle X^2$&\mkcstyle{\scriptstyle}{X}\cr}
Produces: See typeset version.

Comments:

  • This example makes a table showing each of the styles. The table only has seven columns because cramped display style is the same as cramped text style [141].
  • Lines 1-9 define a macro which coerces an expression into one of the cramped styles. The macro is a variation of ideas on page 141 of the actual `.tex' file for The TeXbook.
  • The height of the superscript is different in each column. This is particularly apparent on the second line which uses an uppercase `X'.
TeXbook References: 140-141. Also: 140-142, 292, 362.

Related Primitives: textstyle, scriptstyle, scriptscriptstyle, textfont, fam.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

displaywidowpenalty Math (Penalties)
50 * Parameter (integer)
Synopsis: \displaywidowpenalty

Description:

    IF a display interrupts a paragraph, TeX typesets the paragraph lines before the display, the line (or lines) in the display, and the paragraph lines after the display. This penalty is added immediately after the penultimate line before the display. It tells TeX to try to avoid starting a new page with a widow\mkindex{widow line} line immediately followed by a display [104]. If the Plain TeX value of \predisplaypenalty is used, TeX also tries to avoid starting a new page with a display [189].
TeXbook References: 104. Also: 104, 272, 348.

Related Primitives: predisplaypenalty, widowpenalty.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

displaywidth Math (Paragraph)
Parameter (dimen)
Synopsis: \displaywidth

Description:

    WHEN TeX reads the opening $$ of a math display, it sets \displaywidth to the current line width. Normally, that value is \hsize, but it depends on the paragraph shape specified by \parshape and on hanging indentation. In the latter two cases TeX figures the width using line 1 if the display begins the paragraph or line `\prevgraf+2' if the display occurs after \prevgraf lines. TeX uses \displaywidth in deciding how much glue to put before and after the display and where to position the display on its line. The parameter may be changed inside a display, and TeX uses the last value it encounters in the display [189]. Alignment displays do not use this parameter [190].
Example:

     \def\tfn#1#2%
     {%
        The Fibonacci numbers are defined by: $F_0=1$, $F_1=1$, and
        $$
          \displaywidth=#1
          F_n = F_{n-1} + F_{n-2} \hbox{, for } n \ge 2.
        $$
        A related sequence $\{v_n\}$ is: 2, 1, 3, 4, 7, 11, 18, \char144\ It
        satisfies $v_n$ = $x^n + y^n$, where $x = (1 + \sqrt 5)/ 2$
        and $y = (1 - \sqrt 5)/ 2$.
        \vskip#2
     }
     \tfn{\hsize}{1\baselineskip}
     \tfn{0.5\hsize}{0pt}
Produces: See typeset version.

Comments:

  • This example typesets the same paragraph with two different values for \displaywidth. The first using \hsize results in an expression centered between the margins. The second using ½ \hsize results in a display shifted left. Of course, the second makes an overfull box if the display is wider than the new display width.
TeXbook References: 188. Also: 188, 190, 274, 349.

Related Primitives: displayindent, predisplaysize, abovedisplayskip.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

divide Registers
Command
Synopsis: \divide<numeric variable> by <number>

Description:

    THIS command divides the <numeric variable> by <number>. The number must be a nonzero integer [118]. A numeric variable is: a) a parameter of type: integer, dimen, glue, or muglue; b) a token specified by \countdef, \dimendef, \skipdef, or \muskipdef; or c) a \count, \dimen, \skip, or \muskip register. The by is optional [276].
Example:

  1. \def\fixdimens#1#2% Want #1*#2/1000 and (#1*#2/1000)*1.2
  2. {%
  3.   \bgroup
  4.      \dimen1=#1pt
  5.      \count2=#2
  6.      \count1=\dimen1
  7.      \multiply\count1 by \count2
  8.      \divide\count1 by 1000
  9.      \dimen1=\count1 sp
 10.      \dimen2=1.2\dimen1% Note, `\multiply\dimen1 by 1.2' generates an error!
 11.      Original point size = #1pt with  multiplier = #2 makes:
 12.      \the\dimen1/\the\dimen2.\par
 13.   \egroup
 14. }
 15. \count1=1
 16. Before fixdimens, count1 = \the\count1.\par
 17. \fixdimens{10}{1000}
 18. \fixdimens{10}{968}
 19. \fixdimens{24}{1044}
 20. After fixdimens, count1 = \the\count1.
Produces: See typeset version.

Comments:

  • The comment on line 1 shows what \fixdimens is supposed to compute.
  • If the product #1*#2 is computed in a \dimen register, the result can easily overflow the register (i.e., be larger than 16384pt). So, line 6 moves \dimen1 to \count1, and the calculations on lines 7-8 are done using \count registers. The result is moved back to \dimen1 by line 9. The trailing sp means use the dimension scaled points with the value in \count1.
  • Line 10 shows how a fractional multiplier may be used in an assignment statement. Compare this statement with the four lines used to do the same thing on the \multiply reference page.
  • Lines 16 and 20 show that \fixdimens did not change the value of \count1. If comments are placed at the start of lines 3 and 13, the register does change.
TeXbook References: 118. Also: 118-119, 218-219, 276, 391, 397, 398, 417.

Related Primitives: advance, multiply, count, dimen, skip, muskip.

For Additional Examples, see: day, ifnum, time, year

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

doublehyphendemerits Paragraph
10000 * Parameter (integer)
Synopsis: \doublehyphendemerits=<number>

Description:

    WHEN TeX is breaking a paragraph into lines, this value is added to the demerits calculated for a line if the line and the previous one end with discretionary breaks [98].
Example:

     \hsize=2.5in%                 The \adjdemerits reference page
     \setbox0=\vbox{\tstory\par}%  holds the definition of \tstory
     \setbox1=\vbox{\adjdemerits=0
     \doublehyphendemerits=100000
     \tstory\par}
     \hbox{\box0\kern0.25in\box1}
Produces: See typeset version.

Comments:

  • The paragraph on the left has two potential hyphenation problems: two consecutive lines are hyphenated, and the penultimate line is hyphenated.
  • The paragraph on the right sets \doublehyphendemerits to a large value, and the first problem goes away.
  • This example continues on the \finalhyphendemerits reference page.
TeXbook References: 98. Also: 98, 273, 348, 451.

Related Primitives: adjdemerits, finalhyphendemerits.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

dp Box
Internal Quantity
Synopsis: \dp<8-bit register number>

Description:

    EVERY box has a depth which is a <dimen> quantity. When material is placed in a box, the depth of the box is automatically recomputed. The depth may be accessed or changed using \dp<number> [120].
Example:

  1. \setbox0=\hbox{Every box has }
  2. \setbox1=\hbox{a }
  3. The depth of box 0 is \the\dp0.\par
  4. The depth of box 1 is \the\dp1.\par
  5. \hbox{\box0\copy1 depth}
  6. The depth of box 0 is \the\dp0.\par
  7. The depth of box 1 is \the\dp1.\par
Produces: See typeset version.

Comments:

  • Initially, both boxes have a positive depth. Line 5 empties \box0, and its depth becomes 0.
TeXbook References: 120. Also: 120, 271, 316, 388-389, 417.

Related Primitives: ht, wd, setbox.

For Additional Examples, see: afterassignment, boxmaxdepth, prevdepth

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

dump Job
Command
Synopsis: \dump

Description:

    IN INITEX this outputs a format file that can be loaded at high speed to restore the current status. In production versions of TeX, \dump acts like \end [283].
TeXbook References: 283. Also: 283, 286, 336, 344.

Related Primitives: end, everyjob.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

edef Macro
Command
Synopsis: \edef<control sequence><parameter text>{<replacement text>}

Description:

    THIS command defines a macro whose replacement text is expanded when TeX encounters the definition, not each time TeX encounters the macro's control sequence [215]. However, not quite everything in the replacement text is expanded at definition time. For example, token lists produced by \the and a token following \noexpand are not expanded [216]. The three prefixes (\global, \long, and \outer) can be applied to \edef in any order, and they can appear more than once [275].
Example:

  1. \def\tc{\hskip10pt}
  2. \def\ta{Bye\tc Bye}
  3. \edef\tb{Bye\tc Bye}
  4. 1. \ta\tb.\par
  5. \begingroup
  6. \def\tc{\hskip20pt}
  7. 2. \ta\tb.\par
  8. \endgroup
  9. 3. \ta\tb.\par
Produces: See typeset version.

Comments:

  • This example illustrates when the expansion of a macro's definition occurs.
  • Lines 2-3 define two macros which use a third macro defined on line 1.
  • Line 4 typesets each of the two macros.
  • Lines 5-8 hold a new group and contain a new definition for the common macro. The macro defined using \def uses the new definition, but the macro defined using \edef does not.
  • Line 9 typesets the macros a third time. The results are the same as the first time since lines 4 and 9 are in the same group, and no redefinitions occurred in that group.
TeXbook References: 215-216. Also: 215-216, 275, 328, 348, 373-374.

Related Primitives: def, xdef, global, long, outer.

For Additional Examples, see: advance, xdef

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

else Logic
Command
Synopsis: \else

Description:

    THIS separates the true part of a conditional command from the false part. If there is no false part, the \else may be omitted [207]. It is used with \ifcase to specify the all other cases part of that construction [210].
Example:

  1. \def\trefont#1#2% font size & face.
  2. {%
  3.      \ifcase#1 % select font size
  4.           \or\selffamily AA
  5.           \or\selffamily AB
  6.           \or\selffamily AC
  7.           \or\selffamily AD
  8.           \or\selffamily AE
  9.           \or\selffamily AF
 10.           \or\selffamily AG
 11.           \or\selffamily BA
 12.           \else\selffamily AC
 13.      \fi
 14.      \ifcase#2 % select font face
 15.           \or\rm
 16.           \or\it
 17.           \or\bf
 18.           \or\bi
 19.           \else\rm
 20.      \fi
 21. }
 22. \trefont{1}{2}Now, \trefont{3}{1}is the time for {\it all}
 23.  {\trefont{4}{1}men} to come to the aid of \trefont{2}{3}their
 24.  \trefont{10}{3}country.
Produces: See typeset version.

Comments:

  • This example uses \else with two \ifcase statements.
  • Lines 3-13 select a font size and an expected value is 1-8. If 0 is passed, no change in size is made, but if another invalid number is passed, the size changes to AC which is the normal size.
  • Lines 14-20 select a font face and an expected value is 1-4. This works similarly to the font size.
TeXbook References: 207, 210. Also: 207, 210, 213.

Related Primitives: fi, ifcase, or.

For Additional Examples, see: day, fi, futurelet, ifdim, ifhbox, ifhmode, time

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

emergencystretch Paragraph
0pt * Parameter (dimen)
Synopsis: \emergencystretch=<dimen>

Description:

    TEX will make up to three attempts to break a paragraph into lines. The first two use \pretolerance and \tolerance [97]. TeX only makes the third attempt if \emergencystretch is positive. In that case TeX adds \emergencystretch to the stretch in the line when the text must stretch to fill an hbox of the correct width. This decreases \badness [107].
Example:

     \hsize=2.0in\parindent=0pt
     \pretolerance=100
     \tolerance=200
     \emergencystretch=0pt
     \setbox0=\vtop{\tstory\par}%  The \adjdemerits reference page holds the
     \setbox1=\vtop{\emergencystretch=1em\tstory\par}% definition of \tstory
     \hbox to 4.5in{\box0\hfil\box1}
Produces: See typeset version.

Comments:

  • The paragraph on the left is typeset using default values for: \pretolerance, \tolerance, and \emergencystretch. It contains one overfull line. The paragraph on the right sets \emergencystretch=1em, and the overfull line goes away.
  • If \hsize is changed to 1.5in, the left paragraph has 6 overfull lines, and each goes away when \emergencystretch=1em.
  • The \tolerance reference page contains an example when \hsize=1.25in.
TeXbook References: 107. Also: 107, 274.

Related Primitives: pretolerance, tolerance, badness.

For Additional Examples, see: pretolerance

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

end Job
Command
Synopsis: \end

Description:

    NORMALLY, the last command in a document is \end [87]. It ends the current job only if the main vertical list is empty and \deadcycles=0. If either condition is not true, TeX inserts `\hbox to \hsize{} \vfill \penalty -'10000000000' into the main vertical list and then prepares to reread the \end (the penalty is in octal and is -230). Generally, this is sufficient to flush out all remaining output [264]. The command is not allowed in internal vertical mode [283] or restricted horizontal mode. In horizontal mode TeX ends the current paragraph and then rereads \end [286].
Example:

     \vfill\eject
     \end
Produces: See typeset version.

Comments:

  • The example shows the preferred way to end a document. It will work fine for most simple things. However, a book might require one or more blank pages to be generated to fill out a signature and so might require a more complicated end routine.
TeXbook References: 26-27, 264. Also: 23, 26-27, 87, 264, 283, 286, 299, 336, 403.

Related Primitives: deadcycles, dump.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

endcsname Macro
Command
Synopsis: \endcsname

Description:

    THIS command must terminate a list of tokens begun with \csname. If it does, and if each of the intermediate tokens expands into characters, TeX forms a control sequence token from the characters. If there is no preceeding \csname or a primitive occurs in one of the intermediate tokens, TeX reports an error [40]. If the newly formed control sequence is currently undefined, it is defined to be like \relax [213]. The pair of commands (\csname and \endcsname) allows a document or formatting routine to build a control sequence token on the fly [nr].
Example:

  1. \def\getrcount#1{\csname ref#1count\endcsname}
  2. \def\getrdesc#1{\csname ref#1desc\endcsname}
  3. \halign
  4. {\qquad\hfil#\hfil&\quad\hfil#\hfil&\quad#\hfil\cr
  5. \bf Name&\bf Count&\bf Description\cr
  6. B&\getrcount B&\getrdesc B\cr
  7. A&\getrcount A&\getrdesc A\cr
  8. C&\getrcount C&\getrdesc C\cr
  9. }
Produces: See typeset version.

Comments:

  • These lines continue an example begun on the \csname reference page.
  • Lines 1-2 would normally be in a formatting file immediately after the \mkr macro shown in the \csname example. The lines form the link between the document and the count and description macros setup there.
  • Lines 3-9 typeset a table holding the material prepared in the earlier example.
TeXbook References: 40, 213. Also: 40-41, 213, 283, 348, 375.

Related Primitives: csname.

For Additional Examples, see: csname, endcsname, noexpand, the

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

endgroup Macro
Command
Synopsis: \endgroup

Description:

    THIS command creates an error unless TeX is in a group begun by \begingroup. If it is, each item changed by a non-global assignment in the group has its pre-group value restored. Also, the group is ended, but the mode is not changed [279]. Groups begun by `{' and \begingroup must be properly nested; `{\begingroup}\endgroup' generates an error [21].
Example:

     \def\tfixcomments
     {%
          \begingroup
          \parindent=\parindentA
          \everypar={\llap{\hbox to \parindent{\char149\hss}}%
               \hangindent=\parindent\hangafter=1 }% Don't change this to =1}!
     }%
     So, to summarize:\par
     \tfixcomments
     The point is . . . \par
     We don't really know . . . \par
     Who will be held responsible?\par
     \endgroup
     Are there any questions?\par
     No. Good!
Produces: See typeset version.

Comments:

  • The \begingroup reference page shows one typical use of `\begingroup ... \endgroup'. This example shows a second use.
  • The \tfixcomments macro begins a new group and gives \everypar a value appropriate for a bullet list.
  • Later in the document \tfixcomments appears. It turns each of the subsequent paragraphs into an item in a bullet list.
  • Finally, when an \endgroup appears, the group is terminated, and \everypar returns to its previous value.
TeXbook References: 21, 279. Also: 21, 249, 262, 279, 380, 407, 419.

Related Primitives: begingroup.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

endinput File I/O
Command
Synopsis: \endinput

Description:

    THIS command causes TeX to stop processing an \input file at the end of the current line [214]. This provides a way for a macro file to keep from being loaded twice by a document [383].
Example:

  1. \input a % a.tex holds the line: \input c
  2. \input b % b.tex holds the line: \input c
  3. % c.tex holds the following lines: (see page 383 of The TeXbook).
  4. \ifx\xxcyy\relax % use \xxfile_nameyy or anything unique.
  5.      \endinput
  6. \else
  7.      \let\xxcyy=\relax
  8. \fi
  9. % This is where c.tex really starts.
 10. \newread\tr% We don't want to allocate \tr twice !
Produces: See typeset version.

Comments:

  • The above lines provide one solution to a problem described on the \input reference page.
  • Lines 1-2 cause c.tex to be loaded. On the \input page that causes \tr to be allocated twice.
  • This time c.tex begins by comparing a made up control sequence (which should be unique) to \relax.
  • When c.tex is loaded for the first time, the test made on line 4 fails. So, line 7 is performed, and the rest of c is loaded.
  • If c is loaded a second time, the test on line 4 passes, and \endinput is done.
TeXbook References: 214, 383. Also: 47, 214, 383.

Related Primitives: input.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

endlinechar Character
13 (^^M) * Parameter (integer)
Synopsis: \endlinechar

Description:

    TEX reads an input file a line at a time and converts the material to a sequence of tokens [38]. At the end of each line it deletes any spaces it finds and inserts a character token holding the current value of \endlinechar [46]. If \endlinechar is less than 0 or greater than 255, nothing is added [48]. The Plain TeX \path macros use \endlinechar=-1 [390-391].
TeXbook References: 48, 273. Also: 48, 273, 331, 348, 390-391.

Related Primitives: escapechar, newlinechar.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

eqno Math
Command
Synopsis: \eqno<formula>

Description:

    THIS command puts an equation number at the right-hand margin [186]. It may only be used in display math mode. TeX processes the material for the number as follows: a) it enters a new level of grouping and begins non-display math mode; b) it adds the \everymath tokens to the new math list; c) it adds everything between the \eqno command and the $$ which ends the display to the math list; d) it converts the math list to a horizontal list which it puts in an hbox. The resulting hbox becomes the equation number [293]. TeX tries the following strategies as it positions the equation number and the display on a line: a) center the display and then place the equation number at the right margin; b) place the equation number at the right margin and then position the display in the remaining space; [187] c) if the display and the equation number are wider than \displaywidth or if the equation number has zero width, center the display; add an infinite penalty; and place the equation number at the right margin on the following line. The infinite penalty prevents TeX from typesetting the display on one page and the equation number on the following page [188-189].
Example:

  1. \def\tfn#1#2% equation number, space.
  2. {%
  3.      $$  u_{-n} = -(xy)^{-n}u_n = (-1)^{n-1}u_n{,}#2 v_{-n} =
  4.          (-1)^nv_n.#1% even left equation numbers go at the end !
  5.      $$%
  6. }
  7. \tfn{\eqno(10.14.5)}{\qquad}
  8. \tfn{\leqno(10.14.6)}{\qquad}
  9. \tfn{\eqno(10.14.7)}{\qquad\qquad}
 10. \tfn{\leqno(10.14.8)}{\qquad\qquad}
Produces: See typeset version.

Comments:

  • This example uses the macro defined on lines 1-6 to typeset four displays.
  • Lines 7-8 use strategy a) described above.
  • The displays made by lines 9-10 are wider, and strategy b) is used.
  • Note line 4. Both left and right equation numbers are typed at the end of the display.
TeXbook References: 187, 293. Also: 186-187, 189-191, 193, 293, 375-376.

Related Primitives: leqno.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

errhelp Debugging
Parameter (token)
Synopsis: \errhelp<general text>

Description:

    THIS token parameter holds a message that is displayed when a user asks for help after encountering an error made by \errormessage [280]. Plain TeX has a \newhelp macro which facilitates the construction of help messages [347].
Example:

  1. \def\checkit#1#2#3% See \errmessage page for another version of \checkit
  2. {{%
  3.      \setbox0=\hbox{#1}%
  4.      \ifdim\wd0 > #2
  5.           \errhelp=\helpcheckitA
  6.           \errmessage{The text #1 has width = \the\wd0, which is wider than #2}%
  7.      \else
  8.           #3. \box0
  9.      \fi
 10. }}
 11. \newhelp\helpcheckitA{Try increasing the dimen used to check the text.}
 12. \checkit{Hello World}{60pt}1
 13. \checkit{Hello World}{20pt}2
Produces: See typeset version.

Comments:

  • Lines 1-10 define a macro which is used on lines 12 and 13.
  • Line 11 uses Plain TeX's \newhelp command to define a custom help message for the error message on line 6. This makes line 14 in the log file.
  • Line 12 does not generate an error and typesets its material via line 8.
  • Line 13 does generate an error which makes lines 16-21 in the log file. In response to the `?' on line 21, I entered `h' and TeX displayed the message on line 22. That message came from lines 5 and 11.
  • The extra level of grouping made by lines 2 and 10 keeps the assignment to \errhelp made on line 5 local to \checkit.
TeXbook References: 280. Also: 275, 280, 347.

Related Primitives: errmessage.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

errmessage Debugging
Command
Synopsis: \errmessage<general text>

Description:

    THIS command defines a custom error message written on the terminal and to the log file [279-280]. Tokens in the message are expanded when the message is written [216]. If TeX encounters the command, it interrupts processing; displays the message on the terminal and writes it to the log file; and waits for further instructions [nr].
Example:

  1. \def\checkit#1#2#3% See \errhelp page for another version of \checkit
  2. {%
  3.      \setbox0=\hbox{#1}%
  4.      \ifdim\wd0 > #2
  5.           \errmessage{The text #1 has width = \the\wd0, which is wider than #2}%
  6.      \else
  7.           #3. \box0
  8.      \fi
  9. }
 10. \checkit{Hello World}{60pt}1
 11. \checkit{Hello World}{20pt}2
Produces: See typeset version.

Comments:

  • Lines 1-9 define a macro which is used on lines 10 and 11.
  • Line 10 does not generate an error and typesets its material via line 7.
  • Line 11 does generate an error which makes lines 12-17 in the log file. In response to the `?' on line 17, I entered `h' and TeX displayed lines 18-23. This is the default message TeX displays if there is not an active \errhelp.
TeXbook References: 279-280. Also: 216, 279-280, 347, 418.

Related Primitives: errhelp.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

errorcontextlines Debugging
5 * Parameter (integer)
Synopsis: \errorcontextlines

Description:

    THIS parameter controls the number of extra 2-line messages displayed on the terminal and written to the log file when TeX encounters an error. If \zzz is an undefined control sequence, the number may be increased by entering `I\errorcontextlines= 100\zzz' when TeX interrupts processing, displays error information, and waits for a response [34].
Example:

  1. \def\linkA#1%
  2.      {A \linkB{\linkC{\linkD{\linkE{\linkF{\linkG{\linkH{\linkI{#1}}}}}}}}Z}
  3. \def\linkB#1{B {#1}}
  4. \def\linkC#1{C {#1}}
  5. \def\linkD#1{D {#1}}
  6. \def\linkE#1{E {#1}}
  7. \def\linkF#1{F {#1}}
  8. \def\linkG#1{G {#1}}
  9. \def\linkH#1{H {#1}}
 10. \def\linkI#1{I \hskip2#1 B}% This makes an error unless #1 is a valid dimension
 11. \linkA{inyz}%                This becomes: \hskip2inyz and is OK
 12. \errorcontextlines=-1
 13. \linkA{axyz}%                This becomes: \hskip2axyz and is an error.
 14. \errorcontextlines=0
 15. \linkA{bxyz}
 16. \errorcontextlines=5
 17. \linkA{cxyz}
 18. \errorcontextlines=100
 19. \linkA{dxyz}
Produces: See typeset version.

Comments:

  • Lines 1-10 illustrate a set of deeply nested macros. The parameter `inyz' to \linkA on line 11 is eventually placed after \hskip2 on line 10 and it causes TeX to move right 2 inches and then typeset `yz B'.
  • On lines 13-19 each of the parameters to \linkA does not begin with a valid TeX dimension, so it creates an error. The value assigned to \errorcontextlines on lines 12-18 determines how many pairs of messages TeX displays when it encounters an error.
  • The four errors made by lines 13-19 write four sets of lines to the log file: 20-24, 25-30, 31-46, and 47-71. The first line of each set begins with an `!' and a message. The penultimate line of each set gives the location of the error in the source file, and the last line contains a `?'. It is the clue that TeX is waiting to be told what to do next. If `h' is entered, TeX provides additional help information if any is available. If `?' is entered, TeX displays a list of valid responses and the action it takes for each one.
  • Only lines 38 and 52 in the log file give a helpful clue about the underlying problem.
TeXbook References: 34. Also: 34, 273, 348.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

errorstopmode Debugging
Command
Synopsis: \errorstopmode

Description:

    IF TeX is running in \batchmode, \nonstopmode, or \scrollmode, this command ends that mode and causes TeX to return to its normal level of interaction when errors are encountered. Otherwise, the command has no effect [32].
Example:

  1. \batchmode
  2.   .
  3.   .
  4.   .
  5. \errorstopmode
Produces: See typeset version.

Comments:

  • If TeX encounters errors on lines 2-4, it writes an error message to the log file, but it won't display a message on the terminal or stop for user input.
  • After line 5 TeX resumes normal error processing.
TeXbook References: 32. Also: 32, 33, 277, 299.

Related Primitives: batchmode, nonstopmode, scrollmode.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

escapechar Character
92 (\) * Parameter (integer)
Synopsis: \escapechar

Description:

    THIS specifies the character that should be used when a control sequence is written as text [40] or expanded by \string [213]. Nothing is written if \escapechar is less than 0 or greater than 255 [308].
Example:

  1. \escapechar=-1\string\TeX --- % It doesn't matter how OR if \TeX is defined
  2. \escapechar=63\string\TeX --- %            a ? is 63 and \ is 92.
  3. \escapechar=92\string\TeX  --- wrong!\par
  4. \escapechar=-1 \string\TeX --- %           put a space after the number,
  5. \escapechar=`?\string\TeX ---
  6. \escapechar=`\\\string\TeX  --- wrong!\par
  7. \escapechar=-1 \string\TeX ---
  8. \escapechar=63 \string\TeX ---
  9. \escapechar=92 \string\TeX \par
 10. \escapechar=-1 \string\TeX ---
 11. \escapechar=`?\relax\string\TeX --- %      or use \relax,
 12. \escapechar=`\\{}\string\TeX\par%          or use {}.
Produces: See typeset version.

Comments:

  • Lines 1-3 and 5-6 produce unexpected results. In each case the \string command is processed (using the current value of \escapechar) before the new value is determined.
  • Lines 4 and 7-12 show various ways to avoid the above problem.
TeXbook References: 40. Also: 40, 213, 228, 273, 308, 348, 377.

Related Primitives: string, endlinechar, newlinechar.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

everycr Tables
none * Parameter (token)
Synopsis: \everycr{<token list>}

Description:

    This parameter holds a list of tokens that gets inserted after every \cr or nonredundant \crcr [275].
Example:

     \everycr{\noalign{\hrule}}
     \def\strutA#1#2{\vrule height#1 depth#2 width0pt}
     \halign
     {\vrule\strutA{10pt}{4pt}#\tabskip=0.5em&#\hfil&#\vrule&#\hfil&
      #\vrule&\hfil#\hfil&\tabskip=0pt#\vrule\cr
     &\multispan5\it\hfil New York Area Rocks\hfil&\cr
     &\omit\hfil Era\hfil&&\omit\hfil Formation\hfil&&\omit\hfil Age (years)\hfil&\cr
     &Precambrian&& Reading Prong&&   > 1 billion&\cr
     &Paleozoic&&   Manhattan Prong&& 400 million&\cr
     &Mesozoic&&    Newark Basin&&    200 million&\cr
     &Cenozoic&&    Coastal Plain&&   30,000 years&\cr
     }
Produces: See typeset version.

Comments:

  • This example uses \everycr to add the horizontal rules to the table.
  • The table is from ``Tbl-A Program to Format Tables,'' by M. E. Lesk which in turn begins on page 157 of Unix Programmer's Manual, Volume 2, 1983.
TeXbook References: 275. Also: 275, 362.

Related Primitives: cr, crcr.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

everydisplay Math
none * Parameter (token)
Synopsis: \everydisplay{<token list>}

Description:

    This parameter holds a list of tokens that get inserted at the beginning of every display math list [179].
TeXbook References: 179. Also: 179, 275, 287, 326.

Related Primitives: everymath, toks.

For Additional Examples, see: nulldelimiterspace

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

everyhbox Box
none * Parameter (token)
Synopsis: \everyhbox{<token list>}

Description:

    THIS parameter holds a list of tokens that gets inserted at the start of every \hbox [275]. However, if there is an \afterassignment active, and the \hbox appears in a \setbox assignment, then the \everyhbox token list is placed in the \hbox immediately after the \afterassignment token [279].
Example:

     \begingroup
     \everyhbox{\selffamily AD\it}
     \def\badboxes#1#2%
     {%
          \overfullrule=0.25pt
          \setbox0=\hbox spread#2{#1}%
          \setbox1=\hbox{\rm\the\badness}% \rm comes after the \it from \everyhbox
          \setbox2=\hbox to 2.5in{\box0\hfil\box1}%
          \box2
     }
     \badboxes{The badness of this line is: }{-1em}
     \badboxes{The badness of this line is: }{-0.54em}
     \badboxes{The badness of this line is: }{-0.4em}
     \badboxes{The badness of this line is: }{0em}
     \badboxes{The badness of this line is: }{1em}
     \badboxes{The badness of this line is: }{2em}
     \badboxes{The badness of this line is: }{3em}
     \endgroup
Produces: See typeset version.

Comments:

  • The \begingroup and \endgroup commands limit the scope of \everyhbox. Otherwise, a mess can rapidly result.
TeXbook References: 275. Also: 275, 279.

Related Primitives: everyvbox, toks.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

everyjob Job
none * Parameter (token)
Synopsis: \everyjob{<token list>}

Description:

    THIS parameter holds a list of tokens which is inserted at the start of every job [275]. The only example of \everyjob in The Texbook uses it with \dump and hense with INITEX [336].
TeXbook References: 275. Also: 275, 336.

Related Primitives: dump.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

everymath Math
none * Parameter (token)
Synopsis: \everymath{<token list>}

Description:

    THIS parameter holds a list of tokens that get inserted at the beginning of every non-display math list [179]. Since TeX processes equation numbers in non-display math mode, the \everymath tokens are inserted following \eqno and \leqno [293].
TeXbook References: 179. Also: 179, 275, 287, 293, 326.

Related Primitives: everydisplay, toks, eqno, leqno.

For Additional Examples, see: mathsurround, nulldelimiterspace

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

everypar Paragraph
none * Parameter (token)
Synopsis: \everypar{<token list>}

Description:

    THIS parameter holds a list of tokens added at the start of a new paragraph. The sequence is: a) begin a new horizontal list; b) add an empty box with width \parindent (unless the paragraph was begun with \noindent); c) add the tokens in \everypar; d) continue with the rest of the paragraph [105]. Token expansion is suppressed while the token list in \everypar is read [215]. The effects of an \everypar statement may be limited with groups or canceled by saying `\everypar{}' [nr].
Example:

  1. \linenumber=0 % This comes from: \newcount\linenumber
  2. \everypar
  3. {%
  4.      \advance\linenumber by 1%
  5.      \setbox0=\hbox{\the\linenumber.\kern0.75em}%
  6.      \llap{\box0}%
  7. }%
  8. This example contains several short paragraphs as examples.\par
  9. The only real point is to give an example of |\everypar| and to show
 10. that it is easy to number paragraphs.\par
 11. Unfortunately, it is more difficult to number every line in a paragraph.\par
Produces: See typeset version.

Comments:

  • The formatting file used with these pages has a macro called \autolinenumber. Its definition is lines 1-7. It is placed at the start of each Example whose lines should be numbered.
  • Also, the Comments section on these pages uses \everypar to start each paragraph with a bullet and to use hanging indentation.
  • Note, that line numbers are placed out in the left margin, but bullets appear at the start of the left margin.
TeXbook References: 105. Also: 105, 215, 253, 262, 275, 282, 283, 333, 381, 407, 421.

Related Primitives: toks.

For Additional Examples, see: endgroup, pagedepth

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

everyvbox Box
none * Parameter (token)
Synopsis: \everyvbox{<token list>}

Description:

    THIS parameter holds a list of tokens that gets inserted at the start of every \vbox or \vtop [275]. However, if there is an \afterassignment active, and the \vbox appears in a \setbox assignment, then the \everyvbox token list is placed in the \vbox immediately after the \afterassignment token [279].
Example:

  1. \begingroup% Without this group, there are tons of problems!
  2. \everyvbox{\hsize=2in\noindent}
  3. \global\setbox1=\vbox{This is a paragraph without an initial indent. It is
  4.                set justified left and right with \the\hsize\ long lines.}
  5. \global\setbox2=\vtop{\copy1}
  6. \endgroup
  7. \hbox{\box1\kern20pt\raise\dp2\box2}
Produces: See typeset version.

Comments:

  • The \begingroup and \endgroup commands limit the scope ot \everyvbox. Otherwise, a mess can rapidly result.
  • Lines 3 and 5 show \everyvbox works with vboxes and vtops.
  • Line 7 shows a way to force material into two columns.
  • I left extra space on line 4 to make the example easier to read.
TeXbook References: 275. Also: 275, 279.

Related Primitives: everyhbox, toks.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

exhyphenpenalty Penalties (Paragraph)
50 * Parameter (integer)
Synopsis: \exhyphenpenalty

Description:

    WHEN TeX breaks a paragraph into lines, it adds \exhyphenpenalty to the penalties on each line, in its calculation of a line's demerits, if the line ends with a discretionary whose pre-break text is empty (i.e., a word contains a hyphen, and the break is after the hyphen) [96]. The value used for \exhyphenpenalty is the one that is current at the end of the paragraph [101].
Example:

     \def\tstoryB{Several words that include a discretionary are: math-on, math-off and non-discardable.}
     \hsize4.0in
     \exhyphenpenalty=0\tstoryB\par
     \exhyphenpenalty=-400\tstoryB\par
Produces: See typeset version.

Comments:

  • This example is not as dramatic as the one on the \hyphenpenalty reference page, but it shows that \exhyphenpenalty can influence line breaking.
TeXbook References: 96. Also: 96, 262, 272, 348.

Related Primitives: hyphenpenalty, brokenpenalty, discretionary.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

expandafter Macro
Command
Synopsis: \expandafter<token1><token2>

Description:

    THE construction `\expandafter<t1><t2>' is equivalent to `<t1> expansion of <t2>' [213]. TeX does not expand <t1> until after it expands <t2> [215].
Example:

  1. a. \romannumeral\year\par
  2. b. \uppercase{\romannumeral\year}\par
  3. c. \uppercase{a---\romannumeral\year---z}\par
  4. d. \uppercase\expandafter{\romannumeral\year}\par
Produces: See typeset version.

Comments:

  • Line 1 shows that \romannumeral works as expected with \year in producing a lowercase version of the year in roman numerals.
  • However, line 2 shows \uppercase can't be used directly to convert the result from line 1 to uppercase.
  • Line 3 shows \uppercase is not broken. It does convert some things. The problem is one of timing; \uppercase converts the balanced text it finds between `{' and `}', but it does not expand tokens in that text [215]. Later, when TeX does process those tokens, it has no memory of the \uppercase command.
  • Line 4 uses \expandafter to change the order TeX does things. On line 4 <token1> is `{' and <token2> is \romannumeral. TeX saves the `{' and expands \romannumeral. This causes it to expand \year. Once it has the correct lowercase letters, it puts the `{' in front of them, and then \uppercase does its work.
TeXbook References: 213. Also: 40, 213, 215, 260, 308, 330, 348, 374-380.

Related Primitives: afterassignment, aftergroup, futurelet, noexpand.

For Additional Examples, see: csname, iffalse, noexpand, uccode

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

fam Math (Fonts)
-1 * Parameter (integer)
Synopsis: \fam<number>

Description:

    WHEN TeX is in math mode, it typesets material using one of 16 families of fonts. Each family has three fonts: text, script, and scriptscript [153]. In horizontal mode a character is uniquely identified by the two hex digits which give the character's position in the current font. In contrast, a math symbol has an identifying code consisting of three hex digits. The first digit identifies the family, and the next two digits identify the character in the corresponding font. In addition, a fourth digit, the class digit, is often used. It runs from 0-7. The four hex digits are used in various combination to specify \mathcode's [154], \delcode's and \delimiter's [156]. TeX makes only two requirements on the use of family numbers. Families 2 and 3 are reserved for math symbols. Fonts used with these families are required to have additional \fontdimen parameters [157]. Although the preceeding describes several uses of family numbers, it does not describe \fam. TeX sets \fam to -1 every time math mode starts. At any point in a math expression, \fam can be changed. For example, Plain TeX defines \rm to be `\fam=0 \tenrm'. When TeX typesets a math symbol, it checks the symbol's class. If the class is 7, it is changed to 0; and in this case if \fam is between 0 and 15, the family of the symbol is changed from the family specified by \mathcode to the family specified by \fam. This switch plus the assignments made by Plain TeX are what makes `${\rm text }$' typeset `text' in roman instead of in italics [154]. Plain TeX also has \newfam. It is similar to \newcount and allocates family numbers [347].
Example:

  1. \def\tfam
  2. {%
  3.      $ \prtfam1 x^2 \rm\
  4.        \prtfam2 means\ multiply\ \fam=23 x {\rm\ by\ } x \
  5.        \prtfam3
  6.      $ \prtfam4
  7. }
  8. \def\prtfam#1{(#1.\ fam=\the\fam)\ }
  9. \def\rm{\tenrm}\tfam\par
 10. \def\rm{\fam=0 \tenrm}\tfam\par
Produces: See typeset version.

Comments:

  • The macro on lines 1-7 typesets a simple mathematical statement. At several places in the statement, the family number is typeset. Control spaces are required because all text appears in math mode, not in an \hbox.
  • Line 9 defines \rm without changing \fam, and all of the text is typeset in italics.
  • Line 10 defines \rm as Plain TeX does. The text which should be in roman is.
TeXbook References: 154. Also: 154-159, 273, 289-290, 346-347, 351, 358, 414-415, 433.

Related Primitives: textfont, scriptfont, scriptscriptfont, mathcode, delcode, delimiter.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

fi Logic
Command
Synopsis: \fi

Description:

    THIS command ends a conditional command begun by one of the `\if..' commands [207]. Each `\if..' command must have a matching \fi. However, the nesting of `\if ... \fi' is independent of the nesting of `{ ... }' [210].
Example:

  1. \dimen0=20pt
  2. \bgroup
  3.      \dimen0=101pt
  4.      \ifdim\dimen0 > 100pt
  5. \egroup
  6.           TRUE---dimen0 = \the\dimen0
  7.      \else
  8.           FALSE---dimen0 = \the\dimen0
  9.      \fi
Produces: See typeset version.

Comments:

  • This shows a mixed nesting of \if with \bgroup. When the group ends on line 5, the value of \dimen0 reverts to its pre-group value, and that is what lines 6 and 8 print.
TeXbook References: 207, 210. Also: 207, 210, 213.

Related Primitives: else.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

finalhyphendemerits Paragraph
5000 * Parameter (integer)
Synopsis: \finalhyphendemerits=<number>

Description:

    WHEN TeX breaks a paragraph into lines, it adds \finalhyphendemerits to the demerits for the penultimate line in the paragraph if the line ends with a discretionary break [98].
Example:

     \hsize=2.5in
     \setbox0=\vbox{\adjdemerits=0
     \doublehyphendemerits=100000
     \tstory\par}% The \adjdemerits reference page holds the definition of \tstory
     \setbox1=\vbox{\adjdemerits=0
     \doublehyphendemerits=100000
     \finalhyphendemerits=900000
     \tstory\par}
     \hbox{\box0\kern0.25in\box1}
Produces: See typeset version.

Comments:

  • This example continues the example begun on the \doublehyphendemerits page.
  • Originally, the paragraph had two consecutive lines hyphenated in addition to the hyphen on the penultimate line.
  • The addition of the large \doublehyphendemerits removed the two consecutive hyphenated lines. The result is the left paragraph.
  • Several values of \finalhyphendemerits were tried before one large enough to remove the hyphen on the penultimate line was found. The result is the right paragraph.
  • This example is concluded on the \adjdemerits reference page.
TeXbook References: 98. Also: 98, 106, 273, 348, 451.

Related Primitives: adjdemerits, doublehyphendemerits.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

firstmark Marks
Command
Synopsis: \firstmark

Description:

    THIS command holds the mark text that was first encountered on the page that was just boxed. It is null (i.e., empty) before the first page. It is equal to the previous \botmark, when a page contains no marks [258]. The value of \firstmark is global (i.e., it is not affected by grouping) [259].
TeXbook References: 258-260. Also: 213, 258, 259-260, 280.

Related Primitives: mark, botmark, topmark.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

floatingpenalty Penalties
20000 (for footnotes), 0 (for floating top insertions) * Parameter (integer)
Synopsis: \floatingpenalty

Description:

    THIS holds the penalty which is added to \insertpenalties for each unsplit insertion which will not fit on the current page (i.e., the insertion floats to the next page) [123]. Generally, each class of insertions has its own value for \floatingpenalty which is set at some point in the routine used to make the insertion [124 and 363]. The actual value of \floatingpenalty used with a particular class of insertions is the value of the parameter just before the ending `}' of the corresponding \insert [281].
TeXbook References: 123-124. Also: 123-125, 272, 281, 363.

Related Primitives: insertpenalties, insert.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

font Fonts
Internal Quantity
Synopsis: \font<control sequence>=<file name><at clause>

Description:

    THIS command has three forms: a) `\font\cs=filename'; b) `\font\cs=filename at <dimen>'; and c) `\font\cs=filename scaled <number>'. The at form supplies the desired size. TeX divides the number provided with the scaled form by 1000 and uses the result as a scaling factor (e.g., 1200 results in 1.2 and 2000 results in 2). The exact form of filename depends on the operating system used with TeX [16]. If \font is used with \fontname, it denotes the current font [213]. Expansion of tokens is suppressed when TeX is reading a control sequence defined by \font [215]. If TeX runs out of font memory, it prints a message and quits prematurely [300]. TeX allows a document to load at most 256 fonts. Once a font is loaded there appears to be no way to unload the font and reuse the space [nr].
Example:

  1. \def\tmkfont#1#2#3% filename; point size; scale factor;
  2. {%
  3.      \def\emptyB{#2}%
  4.      \def\emptyC{#3}%
  5.      \ifx\emptyB\empty
  6.           \ifx\emptyC\empty
  7.                \global\font\tff=#1 % The space in `#1 %' is required!
  8.           \else
  9.                \global\font\tff=#1 scaled #3 %
 10.           \fi
 11.      \else
 12.           \global\font\tff=#1 at #2 %
 13.      \fi
 14.      . \tff\fontname\tff&
 15.      \tff The quick red fox jumped over the log.\cr
 16. }
 17. \baselineskip=14pt
 18. \halign{&\qquad#\hfil\cr
 19. 1\tmkfont{cmr10}{}{}
 20. 2\tmkfont{cmr10}{12pt}{}
 21. 3\tmkfont{cmr10}{}{1120}% Note, this results in 11.2pt.
 22. 4\tmkfont{pc2k9y}{}{}
 23. 5\tmkfont{pc2k9y}{10pt}{}
 24. 6\tmkfont{pc2k9y}{12pt}{}
 25. 7\tmkfont{pc2k9y}{11.2pt}{}
 26. 8\tmkfont{pc2k9y}{}{1120}
 27. 9\tmkfont{pc2bi9y}{10pt}{}
 28. A\tmkfont{\fontname\font}{11.3pt}{}
 29. }
Produces: See typeset version.

Comments:

  • Lines 7, 9, and 12 illustrate the three forms of \font.
  • Lines 19-21 use each form to typeset a line using ``cmr10'' at 10, 12, and 11.2 points.
  • Lines 22-27 illustrate several ways to load PostScript fonts.
  • Line 28 illustrates one way to change the point size of the current font.
TeXbook References: 16-17. Also: 16-17, 60, 210, 213-215, 271, 276-278.

Related Primitives: fontname, fontdimen, textfont, scriptfont, scriptscriptfont, tracingstats.

For Additional Examples, see: / (italic correction), mathchar

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

fontdimen Fonts
Internal Quantity
Synopsis: \fontdimen<parameter number><font>=<dimen>

Description:

    EVERY font which TeX uses is required to have at least seven \fontdimen parameters [433]. In addition, a math symbol font must have at least 22 parameters and math extension fonts must have at least 13 [433 and 447]. Computer Modern fonts have all necessary parameters defined. PostScript fonts have the necessary seven [nr].
Example:

     \def\trow#1#2%
     {%                          the above Synopsis shows how to SET one of the
          #1 #2&               % fontdimen parameters for a font
          \the\fontdimen#1\rm& % these lines show how to READ the values for a font
          \the\fontdimen#1\it&
          \the\fontdimen#1\bf&
          \the\fontdimen#1\bi\cr
     }
     \halign
     {\qquad#\hfil&&\quad\hfil#\cr
     \multispan5\qquad\hfil\bf The |\fontdimen| parameters for Caslon 224 at 10pt.\hfil\cr
     \noalign{\vskip 0.25\baselineskip}
     \# Meaning&\omit\hfil\rm\fontname\rm&\omit\hfil\it\fontname\it&
                \omit\hfil\bf\fontname\bf&\omit\hfil\bi\fontname\bi\cr
     \trow{1}{slant per pt}
     \trow{2}{interword space}
     \trow{3}{interword stretch}
     \trow{4}{interword shrink}
     \trow{5}{x-height}
     \trow{6}{quad width}
     \trow{7}{extra space}
     }
Produces: See typeset version.

Comments:

  • This example shows the seven \fontdimen parameters for the four basic Caslon fonts at 10pt.
  • Compare this table to the one in the TeXbook prepared for several CM fonts [433]. There, the values in the table are hard coded.
TeXbook References: 443, 447. Also: 76, 157, 179, 214, 271, 277, 355-356, 375, 390, 433, 441, 447.

Related Primitives: font.

For Additional Examples, see: textfont

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

fontname Fonts
Command
Synopsis: \fontname<font>

Description:

    THIS command returns the system file name for <font> which should be: an identifier defined by \font; \textfont<number>, \scriptfont<number>, or \scriptscriptfont <number>; or \font which denotes the current font [213].
Example:

  1. {\selffamily AB\bf Caslon 224 and Helvetica codes and file names}
  2. \halign{\qquad\rm#&\quad\selffamily # \fontname\rm\hfil&\quad\rm#\cr
  3. A&AA&1\cr
  4. B&AB&2\cr
  5. C&AC&3\cr
  6. D&AD&4\cr
  7. E&AE&5\cr
  8. F&AF&6\cr
  9. G&AG&7\cr
 10. A&BA&8\cr
 11. }
Produces: See typeset version.

Comments:

  • This example shows several different roman fonts used in these pages.
  • The preamble on line 2 deserves attention. Each template contains \rm.
  • The first and third templates use the definition of \rm when \halign began. Basically, that definition is: ``Use Caslon roman type at 10 points.''
  • The second template prints the text provided by \fontname\rm. Not only are the words different on each row, but the type size is also different. That means \selffamily must: a) require two parameters (e.g., `AA' on line 3); b) define \rm to be the font written and used on the row; and c) set the current font to the new \rm.
  • Grouping provided automatically by TeX allows the two uses of \rm in the preamble to coexist with each other.
TeXbook References: 213. Also: 213-214.

Related Primitives: font.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

futurelet Macro
Command
Synopsis: \futurelet<control sequence><token1><token2>

Description:

    THE construction `\futurelet\cs=<t1><t2>' has the effect of `\let\cs=<t2><t1><t2>' [207]. TeX doesn't expand tokens when it is reading the argument tokens for \futurelet [215].
Example:

  1. \def\tfl{\futurelet\tchar\tflA}
  2. \def\tflA#1%
  3. {%
  4.      \if \tchar.%
  5.           \let\next=\relax
  6.           #1%
  7.      \else
  8.           \let\next=\tfl
  9.           \if\tchar!%
 10.                --BINGO--%
 11.           \else
 12.                -#1-%
 13.           \fi
 14.      \fi
 15.      \next
 16. }
 17. The next characters are: \tfl  aBcDeFg.\par
 18. The next characters are: \tfl  AbCdEfG.\par
 19. The next characters are: \tfl  (X:!;z).\par
 20. \vskip0.5\baselineskip
 21. \def\tflB#1%
 22. {%
 23.      \if #1.%
 24.           \let\next=\relax
 25.           #1%
 26.      \else
 27.           \let\next=\tflB
 28.           \if #1!%
 29.                --BINGO--%
 30.           \else
 31.                -#1-%
 32.           \fi
 33.      \fi
 34.      \next
 35. }
 36. The next characters are: \tflB aBcDeFg.\par
 37. The next characters are: \tflB AbCdEfG.\par
 38. The next characters are: \tflB (X:!;z).\par
Produces: See typeset version.

Comments:

  • This example illustrates two things.
  • First, lines 1-19 appear to show how \futurelet may be used to aid in processing material one character (or token) at a time.
  • Second, lines 21-38 show \futurelet is completely unnecessary for this task.
TeXbook References: 207. Also: 207, 215, 262, 277, 363, 375-377, 423.

Related Primitives: let, afterassignment, aftergroup, expandafter, noexpand.

For Additional Examples, see: mathchardef

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

gdef Macro
Derived Command
Synopsis: \gdef<control sequence><parameter text>{<replacement text>}

Description:

    THIS command is equivalent to \global\def [206]. The three prefixes (\global, \long, and \outer) can be applied to \gdef in any order, and they can appear more than once [275].
Example:

  1. \def\ta{Bye}
  2. \def\tb{Bye}
  3. 1. \ta\tb.\par
  4. \begingroup
  5. \def\ta{Hello}
  6. \gdef\tb{ World}
  7. 2. \ta\tb.\par
  8. \endgroup
  9. 3. \ta\tb.\par
Produces: See typeset version.

Comments:

  • This example illustrates how \global can change the local nature of a macro's definition.
  • Lines 1-3 define two macros and typeset each of them.
  • Lines 4-8 hold a new group and contain new definitions for the two macros. The definition on line 6 is global.
  • Line 9 typesets the macros a third time. The \ta macro is the same on lines 3 and 9, but the global change made to \tb (inside the group) on line 6 continues after the group ends.
TeXbook References: 206. Also: 206, 215, 275, 352, 407.

Related Primitives: def, global, long, outer.

For Additional Examples, see: mathchardef

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

global Macro
Command
Synopsis: \global<assignment>

Description:

    THIS command makes the immediately following assignment apply to all groups instead of just the current one [21]. The assignment may be a macro assignment (e.g., `\def\ta{text}') or a non-macro assignment (e.g., `\count1=0' or `\advance\count1 by 1') [275]. Non-macro assignments for a particular variable should be always global or always local. Otherwise, it is possible to run out of save stack space [301 and 346].
Example:

  1. \def\tm{}
  2. \begingroup
  3. \def\tm{lost }
  4. \global\def\gtm{will be }
  5. \count2 = 2
  6. \global\count3=3
  7. \advance\count2by5
  8. \global\multiply\count3 by \count2
  9. A. Non-global items \gtm\tm when a group ends.\par
 10. B. The counts are: \the\count2\ and \the\count3.\par
 11. \endgroup
 12. C. Non-global items \gtm\tm when a group ends.\par
 13. D. The counts are: \the\count2\ and \the\count3.\par
 14. \global\count3=0
Produces: See typeset version.

Comments:

  • Lines 9-10 are identical to lines 13-14 except for the letter at the start of each line. However, the non-global changes made in the group on lines 2-11, which are present on lines A and B, are not present on lines C and D.
  • Without line 1, line 12 generates a run-time error (TeX complains that \tm is not defined).
  • Note the presence and absence of spaces on lines 5-8.
TeXbook References: 206, 275. Also: 21, 119, 206, 218, 232, 256, 275, 301, 307, 320, 346.

Related Primitives: begingroup, globaldefs, gdef, xdef, tracingstats.

For Additional Examples, see: afterassignment, setbox

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

globaldefs Macro
0 * Parameter (integer)
Synopsis: \globaldefs

Description:

    NORMALLY, this parameter is 0, and assignments are only global if \global immediately preceeds the assignment. But, if \globaldefs is positive, TeX makes all assignments global. And, if \globaldefs is negative, TeX ignores a \global prefix [275].
Example:

  1. \begingroup
  2. \globaldefs=1
  3. \def\tm{lost }
  4. \def\gtm{will be }
  5. \count2 = 2
  6. \count3=3
  7. \advance\count2 by 5
  8. \multiply\count3 by \count2
  9. A. Non-global items \gtm\tm when a group ends.\par
 10. B. The counts are: \the\count2\ and \the\count3.\par
 11. \endgroup
 12. C. Non-global items \gtm\tm when a group ends.\par
 13. D. The counts are: \the\count2\ and \the\count3.\par
 14. Globaldefs is now: \the\globaldefs.
 15. \global\count2=0\global\count3=0
Produces: See typeset version.

Comments:

  • This example is nearly identical to the one on the \global reference page.
  • The primary difference is line 2. It makes all subsequent assignments global.
  • Line 14 shows the actual assignment made to \globaldefs on line 2 is local.
TeXbook References: 275. Also: 238, 273, 275.

Related Primitives: global.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

halign Tables
Command
Synopsis: \halign<box specification>{<alignment material>}

Description:

    THERE are three forms of \halign: `\halign {material}' [235]; `\halign to <dimen> {material}'; and `\halign spread <dimen> {material}' [238]. The alignment material consists of two parts: a) the preamble which consists of a number of templates describing each column in the table, and b) the rows of the table. A `&' (category code 4) is used to separate templates in the preamble and columns in each row of the table [231 and 235]. Spaces are ignored after a `&' [236]. Exactly one `#' (category 6) must appear in each template in the preamble. It means: ``Put the text for this column here.'' The preamble and each row must end with either \cr or \crcr [235]. Vertical rules are placed in a table by: a) using the Plain TeX macro \offinterlineskip or an equivalent to stop TeX from putting glue between the lines of the table; b) putting a strut with the correct height and depth on each line in the table; and c) creating a template containing \vrule every place a vertical line is needed in the table [245-246]. Horizontal rules are placed in a table by saying `\noalign{\hrule}' after a \cr or \crcr [246]. An \halign command is not allowed in restricted horizontal mode or in math mode. In horizontal mode it causes the current paragraph to end. It is allowed in display math mode only if the current math list is empty [286 and 291].
Example:

  1. \offinterlineskip
  2. \def\tf#1{\omit\hfil #1\hfil}
  3. \def\tfc#1{\omit\hfil\smash{\lower5pt\hbox{#1}}\hfil}
  4. \def\strutA#1#2{\vrule height#1 depth#2 width0pt}
  5. \def\er{\crcr\noalign{\hrule}}
  6. \setbox0=\vbox{\halign
  7. {\strutA{8.5pt}{3.5pt}\vrule#&\kern0.5em#\hfil\quad&\vrule#&\quad\hfil#\quad&
  8. \vrule#&\quad\hfil#\quad&\vrule#&\quad\hfil#\kern0.5em&#\vrule\cr\er
  9. \omit\strutA{10.5pt}{3.5pt}\vrule&\multispan7\hfil\bf 1970 Federal Budget
 10.  Transfers\hfil&\cr
 11. \omit\strutA{8.5pt}{4.5pt}\vrule&\multispan7\hfil\selffamily AG (in billions
 12.  of dollars)\hfil&\er
 13. \omit\strutA{3pt}{0pt}\vrule&\multispan7&\er
 14. \omit\strutA{10.5pt}{3.5pt}\vrule&\tfc{State}&&\tf{Taxes}&&\tf{Money}&&
 15. \tfc{Net}&\cr
 16. \omit\strutA{8.5pt}{5.0pt}\vrule&&&\tf{collected}&&\tf{Spent}&&&\er
 17. \omit\strutA{10.5pt}{3.5pt}\vrule&New York&&   22.91&& 21.35&& -1.56&\cr
 18. &New Jersey&&  8.33&&  6.96&& -1.37&\cr
 19. &Connecticut&& 4.12&&  3.10&& -1.02&\cr
 20. &Maine&&       0.74&&  0.67&& -0.07&\cr
 21. &California&& 22.29&& 22.42&& +0.13&\cr
 22. &New Mexico&&  0.70&&  1.49&& +0.79&\cr
 23. &Georgia&&     3.30&&  4.28&& +0.98&\cr
 24. &Mississippi&& 1.15&&  2.32&& +1.17&\cr
 25. \omit\strutA{8.5pt}{5.5pt}\vrule&Texas&&       9.33&& 11.13&& +1.80&\er
 26. }}
 27. \hbox to \pagewidthB{\hfil\box0\hfil}
Produces: See typeset version.

Comments:

  • This example continues a multi-reference page example of a table. The previous version is on the \noalign reference page, and the example began on the \cr reference page.
  • This version adds final polish to the table. It puts part of the header in bold (line 9) and repositions the words State and Net (lines 3 and 14). Finally, it centers the table on the page (lines 6 and 27).
  • The table appeared on the first page of ``Tbl-A Program to Format Tables,'' by M. E. Lesk which in turn begins on page 157 of Unix Programmer's Manual, Volume 2, 1983.
TeXbook References: 235-249. Also: 117, 190, 193-194, 235-249, 282, 286, 291, 302, 326, 352, 361-362, 386, 392.

Related Primitives: cr, noalign, omit, span, tabskip, crcr, everycr, valign.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

hangafter Paragraph
1 * Parameter (integer)
Synopsis: \hangafter=<number>

Description:

    TEX provides two alternatives to the normal paragraph shape. One is hanging indentation. It removes a rectangular region from one of the four corners of a normal paragraph. Two parameters control the size of the rectangle which is removed: \hangafter and \hangindent. Let n be the value for \hangafter. Then if n >= 0, hanging indentation occurs on lines n+1, n+2, ... of the paragraph, but, if n < 0, it occurs on lines 1, 2, ..., |n| [102]. A normal paragraph is made if \hangafter=1 and \hangindent=0pt. TeX resets \hangafter to its default value at the end of every paragraph [103] and when it enters internal vertical mode [349].
Example:

     \setbox2=\hbox{\dcrm T}%
     \hangafter=-2
     \hangindent=\wd2
     \hsize=4.75in
     \noindent
     \tstory\par% The \adjdemerits reference page holds the definition of \tstory
Produces: See typeset version.

Comments:

  • The small box in the upper-left corner was designed to hold a large Capital `T'. This illustrates the first step in making a dropcap.
TeXbook References: 102-103. Also: 102, 103-104, 273, 348-349, 419.

Related Primitives: hangindent, parshape, prevgraf.

For Additional Examples, see: displayindent, endgroup, prevgraf

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

hangindent Paragraph
0pt * Parameter (dimen)
Synopsis: \hangindent=<dimen>

Description:

    TEX provides two alternatives to the normal paragraph shape. One is hanging indentation. It removes a rectangular region from one of the four corners of a normal paragraph. Two parameters control the size of the rectangle which is removed: \hangafter and \hangindent. Let x be value for \hangindent. The lines with hanging indentaion have width `\hsize - x'. If x > 0, the indentation appears at the left margin, otherwise it appears at the right margin [102]. A normal paragraph is made if \hangafter=1 and \hangindent=0pt. TeX resets \hangindent to its default value at the end of every paragraph [103] and when it enters internal vertical mode [349].
Example:

     \hsize=4.75in
     \hangafter=3
     \hangindent=-2pc
     \noindent
     \tstory\par% The \adjdemerits reference page holds the definition of \tstory
Produces: See typeset version.

Comments:

  • Since \hangindent is negative, and \hangafter is 3, the rectangle appears at the bottom-right corner of the paragraph.
TeXbook References: 102-103. Also: 102, 262, 274, 349, 407.

Related Primitives: hangafter, parshape.

For Additional Examples, see: displayindent, endgroup, prevgraf

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

hbadness Box
1000 * Parameter (integer)
Synopsis: \hbadness

Description:

    WHEN an \hbox is made, the \badness of the box is compared to \hbadness. If \badness is less than or equal to \hbadness, the box is acceptable [272]. Otherwise, a message is written to the log file, and the box is considered: overfull, tight, loose, or underfull. The distinction between the four types of bad boxes depends on whether the glue in the box shrinks or stretches and on the parameters: \hbadness and \hfuzz. The following table [302] summarizes the possibilities:

    bad box type | glue | additional conditions
overfull | shrink | \hbadness < 100 or excess width > \hfuzz.
tight | shrink | (all other shrink cases)
loose | stretch | \hbadness < \badness <= 100.
underfull | stretch | (all other stretch cases)

TeXbook References: 272, 302. Also: 29, 272, 302, 348, 387-388, 401.

Related Primitives: hfuzz, badness, vbadness.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

hbox Box
Command
Synopsis: \hbox<box specification>{<horizontal material>}

Description:

    THERE are three forms of \hbox: `\hbox {material}'; `\hbox to <dimen> {material}'; and `\hbox spread <dimen> {material}'. The to version makes a box <dimen> wide, and the spread version increases the natural width of the box by <dimen>. The baseline of a constructed \hbox is the baseline of the boxes inside it before they were raised or lowered. The height and depth of the box are the maximum distances the interior boxes are above and below the baseline. The width of the box can be negative if the box contains a negative \kern or \hskip [77]. When \hbox is used in horizontal mode, it adds material to the current paragraph. When it is used in vertical mode, it adds material to the current page [86]. An \hbox is indivisible. TeX will not split it over two lines [93].
Example:

  1. This is \hbox{an interrupted} line.\par
  2. This is \hbox spread 1em{also an interrupted} line.\par
  3. \hbox to 3in{\vrule\hfil This is a centered line.\hfil\vrule}\par
Produces: See typeset version.

Comments:

  • The extra glue introduced by the spread version of hbox is left in line 2.
TeXbook References: 77, 278. Also: 64-67, 77, 86, 93, 151, 159, 163, 175, 179, 185-186, 221, 222, 278, 282, 388-389.

Related Primitives: setbox, vbox, vtop.

For Additional Examples, see: cleaders, ifodd, leaders, mathchoice, vskip, vss

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

hfil Glue
Derived Command
Synopsis: \hfil

Description:

    THIS command is essentially equivalent to: `\hskip 0pt plus 1fil' [72]. If \hfil appears in vertical mode, a new paragraph is started [283]. It appends horizontal glue to horizontal [285] and math [290] lists. It is used behind the scenes with \over [142] and \matrix [177] to center material. Also, the Plain TeX macro \displaylines uses \hfil to center each line in the display [194].
Example:

     {\bf Commands used for Glue or Kern}
     \halign
     {\qquad#\hfil&\quad\hfil#&\quad\hfil#\hfil\cr
     hskip&vskip&kern\cr
     hfil&vfil&lower\cr
     hfill&vfill&raise\cr
     hfilneg&vfilneg&moveleft\cr
     hss&vss&moveright\cr
     }
Produces: See typeset version.

Comments:

  • This example shows that in an alignment: `#\hfil' left justifies text; `\hfil#' right justifies text; and `\hfil#\hfil' centers text.
TeXbook References: 71-72. Also: 71-72, 194, 235-237, 283, 285, 290, 397.

Related Primitives: hskip, hfill, hfilneg, hss.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

hfill Glue
Derived Command
Synopsis: \hfill

Description:

    THIS command is essentially equivalent to: `\hskip 0pt plus 1fill' [72]. If \hfill appears in vertical mode, a new paragraph is started [283]. It appends horizontal glue to horizontal [285] and math [290] lists. It may be used with \over [142], \matrix [177], and \displaylines [194] to place material flush left or right.
Example:

  1. \hbox to 3.5in{\vrule\hskip0pt plus2fill Here is an oddly
  2. placed line.\hfill\vrule}
  3. \hbox to 3.5in{\vrule\hskip0pt plus1.75fill Here is another
  4. one.\hfill\vrule}
  5. \hbox to 3.5in{\vrule\hskip0pt plus16383.9fil Here is a left
  6. justified line.\hfill\vrule}
  7. \vskip1\baselineskip
  8. $ x\over(x+1)$, $ x\hfil\over(x+1)$, $ x\hfill\over(x+1)$
Produces: See typeset version.

Comments:

  • The white space at the start of the first line is exactly twice the space at the end of the line.
  • Lines 3-4 show a fractional quantity may be used with \hskip and one of the fils to produce more complicated results.
  • Lines 5-6 show that 1 fill is larger than 16383.9 fil. Quantities appearing before one of the fils must be less than 16384 [72].
  • Line 8 shows that spacing similar to that from lines 1-4 results if \hfil is used with \over. However, \hfill works as it does in lines 5-6.
TeXbook References: 71-72. Also: 71-72, 142, 177, 194, 233, 283, 285, 290.

Related Primitives: hskip, hfil.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

hfilneg Glue
Derived Command
Synopsis: \hfilneg

Description:

    THIS command is essentially equivalent to: `\hskip 0pt plus -1fil'. It cancels the stretchability of \hfil [72]. If \hfilneg appears in vertical mode, a new paragraph is started [283]. It appends horizontal glue to horizontal [285] and math [290] lists.
Example:

  1. \def\cline #1{\hbox to 3in{\vrule\hfil #1\hfil\vrule}}
  2. \cline{This line is centered.}
  3. \cline{This line is NOT centered.\hfilneg}
  4. \cline{\hfilneg This line is NOT centered.}
  5. \vskip1\baselineskip
  6. $ x\over(x+1)$, $ \hfilneg x\over(x+1)$, $ x\hfilneg\over(x+1)$
Produces: See typeset version.

Comments:

  • Line 1 defines a variation of Plain TeX's centerline macro. It creates a 3-inch wide work area and puts vertical lines at each end of the area.
  • Line 2 shows a normal use of \cline.
  • Lines 3-4 show how \hfilneg can be used to undo part of what \cline does.
  • Line 6 is similar to lines 2-4 and shows how \hfilneg acts with \over.
TeXbook References: 72. Also: 72, 100, 233, 283, 285, 290, 397.

Related Primitives: hskip, hfil.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

hfuzz Box
0.1pt * Parameter (dimen)
Synopsis: \hfuzz

Description:

    THIS is a dimen parameter used with \hbadness in classifying an \hbox which contains more material than will fit even after the glue in the box has shrunk all it can. TeX considers the box overfull if the excess width of the box is larger than \hfuzz or \hbadness is less than 100 [302].
TeXbook References: 274, 302. Also: 30, 274, 302, 348, 387-388.

Related Primitives: hbadness, vfuzz.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

hoffset Page
0pt * Parameter (dimen)
Synopsis: \hoffset=<dimen>

Description:

    THIS parameter controls the location of each typeset page's left margin. The default value of \hoffset is 0pt, and TeX makes a 1-inch left margin. That margin is moved to the right if \hoffset is given a positive dimension and to the left if it is given a negative dimension [251].
Example:

  1. \def\theadline
  2. {%
  3.      \ifodd\pageno
  4.           \global\hoffset = 0.8125in% 13/16
  5.           \hcropmark(-1.7125,00.7)%   upper left - ODD page
  6.           \vcropmark(-1.3125,00.2)
  7. %         make other ``odd'' page assignments, e.g., cropmarks.
  8.      \else
  9.           \global\hoffset = 0.5625in% 9/16
 10.           \hcropmark(-1.4625,00.7)%   upper left - EVEN page
 11.           \vcropmark(-1.0625,00.2)
 12. %         make other ``even'' page assignments, e.g., cropmarks.
 13.      \fi
 14. %    Put material which will NOT appear on the cropped pages.
 15.      \ifcase\headnum\vskip 71pt%  0. no header
 16.      \or\firstheadline   %        1. 2 lines only
 17.      \or\regheadline     %        2. 2 lines + text - normal.
 18.      \fi
 19. }
Produces: See typeset version.

Comments:

  • This example shows part of a macro which is called by the output routine and makes the header line on these reference pages.
  • The quarter of an inch difference in \hoffset (lines 4 and 9) shows up on the left side of each odd page. It provides the extra space required for the binding.
  • The macro prints identification data above the top of the page (line 14).
  • The macro uses \headnum to print one of three possible headers (lines 15-18).
TeXbook References: 251. Also: 251, 274, 342.

Related Primitives: voffset, hsize, vsize.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

holdinginserts Inserts
0 * Parameter (integer)
Synopsis: \holdinginserts=<number>

Description:

    IF this parameter is positive, when the current page is placed in \box255 and sent to the output routine, all insertions are held in their places (i.e., the \box for each class of insertions is left empty) [125].
TeXbook References: 125. Also: 125, 273, 400.

Related Primitives: insert.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

hrule Box
Command
Synopsis: \hrule[height<dimen> depth<dimen> width<dimen>]

Description:

    A rule box is a solid black rectangular box with a height, depth, and width. Such a box may look like a horizontal or vertical line. The \hrule command makes a rule box, and it usually is used in vertical mode. If none of the box dimensions are specified, the box has height 0.4pt and depth 0pt. Its width is the width of the smallest box that encloses it. No interline glue is placed before or after an \hrule [221]. Normally, when \hrule is used in horizontal mode, the paragraph is ended, and the rule box is typeset [222]. However, \hrule may be used with \leaders in horizontal mode with no unexpected effects [224-225].
Example:

  1. \vtop{\hsize=3in
  2. Here is a square hrule: \hrule width 0.25in height0.125in depth 0.125in\par
  3. Here is an hrule \hrule width 1in in a line.\par
  4. Here is the first line of text.\par
  5. \hrule
  6. Here is the second line of text.\par
  7. \vskip .5\baselineskip
  8. \hrule height 0.25pt%                   this makes a `thinner' line.
  9. \vskip .5\baselineskip
 10. Here is the third line of text.\par
 11. }
Produces: See typeset version.

Comments:

  • Line 2 makes it look as if the square should appear at the end of the first typeset line, but it does not. It is typeset by itself on the next line.
  • Line 3 illustrates a variation of the previous comment.
  • Each example illustrates that TeX does not automatically put extra space before or after an \hrule command.
TeXbook References: 221-225. Also: 24, 64, 85, 221-225, 246, 281-282, 286, 357, 420, 421.

Related Primitives: vrule, leaders.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

hsize Paragraph
6.5in * Parameter (dimen)
Synopsis: \hsize=<dimen>

Description:

    THIS dimension determines the width of normal lines in a paragraph [27]. However, the first and last lines in a paragraph are special. The first line is affected by \parindent [101], and the last line is affected by \parfillskip [100]. If a paragraph contains several \hsize commands, TeX uses the last one to typeset the paragraph [101].
Example:

     \tstory\par% The \adjdemerits reference page holds the definition of \tstory
     {\parindent=1.5pc\hsize=4.75in
     \tstory\par}
Produces: See typeset version.

Comments:

  • The first paragraph is typeset using the value for \hsize used by the reference pages. That value is less than the total width of typeset material on the page (e.g., the header line). TeX makes it easy to place material outside the margins determined by hoffset, voffset, hsize, and vsize.
TeXbook References: 26-27, 251. Also: 26-27, 60, 101-102, 188, 237, 251, 257, 274, 340-341, 348, 387, 406, 407, 413, 415, 417.

Related Primitives: parindent, parfillskip, hangafter, hangindent, parshape, vsize, hoffset, voffset.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

hskip Glue
Command
Synopsis: \hskip<glue>

Description:

    THIS command inserts glue in horizontal [285] or math [290] mode. It is used with fil and fill to make \hfil and \hfill. It should not be used with math glue [168]. If \hskip appears in vertical mode, a new paragraph is started [283]. Although filll exists, \hfilll is not a primitive [72].
Example:

  1. Here is a line of text\par
  2. \hskip0.25in Here is a second line of text.\par
  3. \kern0.25in Here is a third line of text.\par
  4. \noindent\kern0.25in Here is a final line of text.\par
Produces: See typeset version.

Comments:

  • Lines 1-2 work as expected.
  • Line 3 produces a surprise. If \hskip appears in vertical mode, a new paragraph is started. However, \kern adds vertical or horizontal space depending on the current mode which is vertical at the start of line 3.
  • The \noindent on line 4 begins a new paragraph, so \kern makes horizontal space.
TeXbook References: 71. Also: 71, 86, 168, 283, 285, 290, 314.

Related Primitives: hfil, hfill, hfilneg, hss, mskip, vskip, kern.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

hss Glue
Derived Command
Synopsis: \hss

Description:

    THIS command is essentially equivalent to: `\hskip 0pt plus 1fil minus 1fil' [72]. If it appears in vertical mode, a new paragraph is started [283]. It appends horizontal glue to horizontal [285] and math [290] lists. It is used in the Plain TeX macro \rlap [82].
Example:

  1. \def\trlap#1{\hbox to 0pt{#1\hss}}
  2. {font {\tt\fontname\font}\ makes: \tt 4 \trlap/= 5. Also 5 \trlap=/ 6.
  3.  \hbox{\kern.25in\boxitA{/}{}\kern0.25in \boxitA{=}{}}}\par
  4. font \fontname\font\ makes: 4 \trlap/= 5. Also 5 \trlap=/ 6.
  5.  \hbox{\kern.6in\boxitA{/}{}\kern0.25in \boxitA{=}{}}
Produces: See typeset version.

Comments:

  • Line 1 defines \trlap. It is the same as Plain TeX's \rlap.
  • Lines 2-3 use \trlap and a fixed-width font to print a not equal symbol.
  • Lines 4-5 are the same except for the font. However, the results from these lines is not usable.
  • The boxes at the end of each line help explain the results.
TeXbook References: 71-72. Also: 71-72, 82-83, 233, 283, 285, 290, 442.

Related Primitives: hskip, hfil.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

ht Box
Internal Quantity
Synopsis: \ht<8-bit register number>

Description:

    EVERY box has a height which is a <dimen> quantity. When material is placed in a box, the height of the box is automatically recomputed. The height may be accessed or changed using \ht<number> [120].
Example:

  1. \setbox0=\hbox{Every box has }
  2. \setbox1=\hbox{a }
  3. The height of box 0 is \the\ht0.\par
  4. The height of box 1 is \the\ht1.\par
  5. \hbox{\box0\copy1 height}
  6. The height of box 0 is \the\ht0.\par
  7. The height of box 1 is \the\ht1.\par
Produces: See typeset version.

Comments:

  • Initially, both boxes have a positive height. Line 5 empties \box0, and its height becomes 0.
TeXbook References: 120. Also: 120, 271, 388-389, 417.

Related Primitives: dp, wd, setbox.

For Additional Examples, see: accent, boxmaxdepth

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

hyphenation Hyphenation
Command
Synopsis: \hyphenation{<hyphenated words>}

Description:

    THIS command adds a set of hyphenated words to the exception dictionary for the current language. For example, the manmac format says: `\hyphenation {man-u-script man-u-scripts ap-pen-dix}' [452]. The exception dictionary is global. If a word is placed in the dictionary more than once, the last addition is the one used [453].
Example:

  1. \def\tstoryA{There are cries, sobs, confusion among the people, and at
  2. that moment the cardinal himself, the Grand Inquisitor, passes by the
  3. cathedral. He is an old man . . .}
  4. {\language255\hyphenation{mom-ent}}
  5. \setbox0=\vbox{\hsize=2.25in \tstoryA}
  6. \setbox1=\vbox{\hsize=2.25in\language255 \tstoryA}
  7. \hbox to \hsize{\box0\hfill\box1}
Produces: See typeset version.

Comments:

  • Line 4 adds a non-standard hyphenation of moment to \language255's execption dictionary.
  • Line 6 uses \language255 to typeset the right-hand copy of \tstoryA.
TeXbook References: 452. Also: 277, 419, 452-453, 455.

Related Primitives: patterns, language.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

hyphenchar Hyphenation
Internal Quantity
Synopsis: \hyphenchar<font>=<number>

Description:

    WHEN TeX loads a new font, it sets the \hyphenchar of the font to the value of \defaulthyphenchar [273]. After a font is loaded, its \hyphenchar may, if necessary, be changed. For example, the manmac format sets \hyphenchar to -1 for each typewriter font it uses. This prevents hyphenation of control sequence names and keywords in The TeXbook [414], because hyphenation of a word is not attempted unless the font used for the first letter of the word has a hyphenchar between 0 and 255 [454]. Most fonts set \hyphenchar to a hyphen `-' [351]. In unrestricted horizontal mode a \discretionary{}{}{} is added after a character whose code is the \hyphenchar of its font (e.g., the `-' in pre-break) and after a ligature formed from a sequence which ends with such a character (e.g., an endash or emdash) [286]. Changes to \hyphenchar are global [nr].
Example:

  1. \def\tstoryA{There are cries, sobs, confusion among the people, and at
  2. that moment the cardinal himself, the Grand Inquisitor, passes by the
  3. cathedral. He is an old man . . .}
  4. \count0=\hyphenchar\font
  5. \setbox0=\vbox{\hsize=2.25in \tstoryA}
  6. \setbox1=\vbox{\hsize=2.25in\hyphenchar\font=166 \tstoryA}% 166 is an emdash
  7. \hbox to \hsize{\box0\hfill\box1}%                          in the encoding
  8. The values are: \the\count0\ and \the\hyphenchar\font.%     used here.
  9. \hyphenchar\font=45 % 45 is a hyphen.
Produces: See typeset version.

Comments:

  • Line 6 changes the \hyphenchar of the current font to an emdash.
  • Lines 4 and 8 show the change is global even though the change was made inside a box.
TeXbook References: 95. Also: 95, 214, 271, 273, 277, 286, 351, 395, 414, 454, 455.

Related Primitives: defaulthyphenchar, discretionary.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

hyphenpenalty Penalties (Paragraph)
50 * Parameter (integer)
Synopsis: \hyphenpenalty

Description:

    WHEN TeX breaks a paragraph into lines, it adds \hyphenpenalty to the penalties on each line, in its calculation of a line's demerits, if the line ends with a discretionary whose pre-break text is nonempty (i.e., TeX has hyphenated a word, and the break is after the hyphen) [96]. The value used for \hyphenpenalty is the one that is current at the end of the paragraph [101].
Example:

     \hsize4.15in
     \def\testhyphenpenalty#1%
     {%
          \hyphenpenalty=#1 %
          \tstory% The \adjdemerits reference page holds the definition of \tstory
          \par
          \vskip1\baselineskip
     }
     \testhyphenpenalty{50}% 0 & 50 make identical paragraphs for this material.
     \testhyphenpenalty{200}
     \testhyphenpenalty{-200}\unskip% remove the last \baselineskip!
Produces: See typeset version.

Comments:

  • This example typesets a paragraph with three different values of \hyphenpenalty.
  • There is no difference in using the Plain TeX value of 50 and using 0.
  • Increasing \hyphenpenalty to 200 eliminates all hyphenated words in the paragraph.
  • Decreaseing \hyphenpenalty to -200 results in two addition hyphenated words.
TeXbook References: 96. Also: 96, 101, 272, 348, 451.

Related Primitives: exhyphenpenalty, brokenpenalty, discretionary.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

if Logic
Command
Synopsis: \if<token1><token2>

Description:

    TEX evaluates an \if command by expanding the tokens following the \if until it finds two unexpandable tokens [209]. Each of those tokens is either: a character (with a character code value 0-255 and a category code value 0-15) or a control sequence [38]. The control sequence is assigned character code 256 and category code 16. The \if condition is true if the character codes of the two tokens are the same. Part of the above expansion involves replacing a token which has in turn been `let=' to another token by the other token [209].
Example:

  1. \def\tmacro#1% a `-' means use default value instead of parameter 1.
  2. {%
  3.      \if -#1
  4.           DV% default value.
  5.      \else
  6.           #1%
  7.      \fi
  8.      ---\par
  9. }
 10. \tmacro{Just a test}% Want to use passed  value of paramter.
 11. \tmacro{-}%           Want to use default value.
 12. \tmacro{- Whoops!}%   Want to use passed  value of paramter.
Produces: See typeset version.

Comments:

  • It is common to write a TeX macro with several parameters and then design the macro so it works one way if a particular parameter is present and a second way if the parameter is absent.
  • This example shows one way to check for a missing or unused parameter. The \ifx reference page shows another way.
  • Lines 3-7 use an \if statement to see if a special character is present in a parameter. Line 12 shows this technique should only be used if the special character will never occur as the first character of the parameter. The result for line 12 makes sense if lines 3-5 are visualized after TeX replaces parameter 1 on line 3: `\if -- Whoops! DV\else'. The test is true, but the result is probably not what was intended.
TeXbook References: 209. Also: 209-211, 307, 377, 379.

Related Primitives: ifcat, ifx.

For Additional Examples, see: afterassignment, futurelet

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

ifcase Logic
Command
Synopsis: \ifcase<number>

Description:

    THIS command begins a conditional which allows for more than two options. Its general form is: `\ifcase<number><text for case 0>\or<text for case 1>\or...\or<text for case n>\else<text for all other cases>\fi'. Here n is an integer greater than or equal to 0; there are n \or statements and an optional final \else which will be used only if the number is negative or larger than n [210].
Example:

  1. \def\mydate
  2. {%
  3.      \number\day \ %
  4.      \ifcase\month
  5.           \or Jan\or Feb\or Mar%
  6.           \or Apr\or May\or June%
  7.           \or July\or Aug\or Sep%
  8.           \or Oct\or Nov\or Dec%
  9.      \fi
 10.      \ \number\year
 11. }
 12. \mydate
Produces: See typeset version.

Comments:

  • The above \ifcase does not have a `0' case or an \else case because \month is an integer between 1 and 12.
  • Without the `%' on lines 5-8, an extra space creaps in for four months of the year.
TeXbook References: 210. Also: 210, 349, 373, 390, 406.

Related Primitives: or, else, fi.

For Additional Examples, see: day, else, mathord

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

ifcat Logic
Command
Synopsis: \ifcat<token1><token2>

Description:

    TEX evaluates an \ifcat command by expanding the tokens following the \ifcat until it finds two unexpandable tokens [209]. Each of those tokens is either: a character (with a character code value 0-255 and a category code value 0-15) or a control sequence [38]. The control sequence is assigned character code 256 and category code 16. The \ifcat condition is true if the category codes of the two tokens are the same. Part of the above expansion involves replacing a token which has in turn been `let=' to another token by the other token [209].
Comments:

  • Useful examples of \ifcat are rare (but see page 377 of The TeXbook).
TeXbook References: 209. Also: 209, 210, 307, 377.

Related Primitives: if, ifx.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

ifdim Logic
Command
Synopsis: \ifdim<dimen1><relation><dimen2>

Description:

    THIS command compares two <dimen> values. The only relations are `<', `>', and `=' which mean less than, greater than, and equal [209]. Each <dimen> should be one of the following: a) a dimen or skip register (e.g., \dimen0 or \skip1); b) an internal quantity or parameter which holds a dimension or glue (e.g., \hsize or \ht0); or c) an actual dimension (e.g., 2.5in or 100pt) [nr]. Glue is converted to a dimension by dropping the stretch and shrink components [118].
Example:

  1. . . .
  2. \ifdim\pagegoal < \maxdimen
  3.      \ifonepage
  4.           \vfill\eject
  5.      \else
  6.           \ifdim\dimen0 < \pagegoal
  7.                \unvbox1
  8.                \penalty200
  9.           \else
 10.                \ifdim\dimen1 < \pagegoal
 11.                     \vfill
 12.                \fi
 13.                \eject
 14.           \fi
 15.      \fi
 16. \fi
 17. \unvbox0
 18. . . .
Produces: See typeset version.

Comments:

  • The above lines are from the macro used to typeset draft versions of these reference pages.
  • They solve a basic problem faced at the start of each new control sequence. Namely, ``is there enough space to get the new cs started on the current page or should the page be ejected and a new page started?''
  • Earlier in the macro box0 is made to hold the cs material through the Synopsis line. Also, box1 is made to hold the material placed between two css which appear on the same page. Finally, \dimen0 and \dimen1 are calculated using the current position on the page, the shrink and stretch in the page, and the space required for boxes 0 and 1.
  • TeX maintains \pagegoal, and it is less than \maxdimen except at the start of a page. In working with early drafts of the pages, I wanted each cs to start on its own page, and so I set \onepagetrue. Later in the project I set \onepagefalse.
  • With the above background it should be straightforward to trace through the lines. TeX only reaches line 3 if the current page has something on it. It only reaches line 6 if two control sequences can appear on the same page. If the material on the current page can shrink enough for both the separation and new material (boxes 1 and 0), the test made on line 6 passes and the separation material is added together with a small penalty which says ``this is not a good place to break the page.'' Otherwise, the page must be ejected (line 13) and the question is whether it has enough on it to stretch and fill out the page. That is the test made on line 10. If there is not, a \vfill is added before the \eject. Finally, the new material is added on line 17.
TeXbook References: 209. Also: 209, 353, 387, 417.

Related Primitives: ifnum.

For Additional Examples, see: accent, fi

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

ifeof Logic
Command
Synopsis: \ifeof<4-bit number>

Description:

    THIS command is true unless the input stream for <number> is open and not fully read. The number must be in the range 0-15 [210].
Example:

  1. %File I/O
  2. %\newread\traux % This appears uncommented in my main formatting routines
  3. %\newwrite\twaux% This appears uncommented in my main formatting routines
  4. %
  5. \def\tfilesetup#1% pass file name. One could also pass: \traux & \twaux.
  6. {%
  7.      \openin\traux=#1 %
  8.      \ifeof\traux
  9.           \closein\traux
 10.      \else
 11.           \closein\traux
 12.           \input #1%
 13.      \fi
 14.      \immediate\openout\twaux=#1 %
 15. }
Produces: See typeset version.

Comments:

  • Some documents require one or more auxilary files (e.g., holding data for the table of contents or index). Normally, TeX is run twice (or more) on such documents. The first run prepares an up-to-date version of the auxilary file, and the second run loads the file and uses it to prepare the final typeset copy.
  • The previous point describes the theory of using TeX. The reality is more complicated because each time TeX processes a document it will load or try to load all the auxilary files required by the document. If an auxilary file is missing (as it may well be) and \input is used to load the file, processing will stop and TeX will complain of a missing file.
  • So, a macro similar to \tfilesetup is used to load each auxilary file. First, the file is opened for reading (line 7). That does not create an error if the file is missing. But, if it is missing or if it is empty, the test on line 8 will fail and the file is simply closed. Otherwise, the file exists and is not empty. So, it is closed and then read using \input. Finally, the file is opened for writing (line 14), and a new version is prepared during the current processing of the main document.
TeXbook References: 210. Also: 210, 217.

Related Primitives: openin.

For Additional Examples, see: openin

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

iffalse Logic
Command
Synopsis: \iffalse

Description:

    THIS is a conditional which is always false. Thus, any text preceeding an accompanying \else will never be used [210]. The command is often used with \mark to set up running headers for the pages of a book or an index [260].
Example:

  1. . . .
  2. % the next line goes in a verso (even) page header.
  3.      \setbox1=\hbox{{\selffamily AC\it\expandafter\iffalse\topmark\fi}}%
  4. . . .
  5. %The next lines are from the macro that makes the reference page for a CS.
  6. %We have: \def\CScs{ControlSequence}, e.g., \def\CScs{iffalse}
  7. %\box0 holds everything through the Synopsis line.
  8. %
  9.      \mark{\currentcs\noexpand\else\CScs}
 10. . . . % do \eject unless following \box0 will fit on current page.
 11. %       The \ifdim reference page shows this test.
 12.      \unvbox0%
 13.      \mark{\CScs\noexpand\else\CScs}
 14. . . . %typeset the rest of the page.
 15.      \let\currentcs=\CScs%
 16. . . .
Produces: See typeset version.

Comments:

  • It is tricky to get the correct control sequence on the header line of these reference pages. Two things are required [260-261].
  • First, a special mark is made before and after the start of each control sequence (lines 9 and 13). Each mark contains two options separated by `\noexpand\else'.
  • Second, each header routine uses either \iftrue or \iffalse and the appropriate mark (\botmark, \firstmark, or \topmark).
  • Some thought and possibly a review of the mark commands should show that line 3 will select the appropriate control sequence for even pages. Keep in mind that the \expandafter on line 3 means: 1) save the \iffalse token; 2) expand \topmark (this makes \cs1\else\cs2 for appropriate values of \cs1 and \cs2); 3) place the token from step 1 before the tokens from step 2 and continue processing.
TeXbook References: 210-211. Also: 210, 211, 260-261, 348, 385-386.

Related Primitives: iftrue.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

ifhbox Logic
Command
Synopsis: \ifhbox<8-bit number>

Description:

    THIS command is true if \box<number> contains an hbox. The number must be a valid box register (i.e., from 0 to 255) [210].
Example:

  1. \def\checkbox#1%
  2. {%
  3.      \ifhbox#1
  4.         \def\tbox{HBox}%
  5.      \else
  6.           \ifvbox#1
  7.                \def\tbox{VBox}%
  8.           \else
  9.                \ifvoid#1
 10.                     \def\tbox{VOid}%
 11.                \else
 12.                     \def\tbox{BigTrouble}%
 13.                \fi
 14.           \fi
 15.      \fi
 16.      {\it box#1: \tbox}%
 17. }
 18. \setbox0=\hbox{Hello World}
 19. \setbox1=\vbox{Going, Going, Gone}
 20. \setbox2=\hbox{Time Out}
 21. \setbox3=\vbox{}
 22. \checkbox0---\checkbox1---\checkbox2---\checkbox3\par
 23. \copy0\box1\box2\copy3
 24. \checkbox0---\checkbox1---\checkbox2---\checkbox3\par
Produces: See typeset version.

Comments:

  • TeX distinguishes between empty\mkindex{box`5`empty vs void} and void boxes. Line 21 creates an empty vbox and assignes it to \box3. Line 23 displays the boxes created on lines 18-21. After line 23 boxes 1 and 2 are void.
  • The \ifhmode reference page shows another way to nest if statements.
  • Each of the percent signs in \checkbox is required to keep out spurious\mkindex{space`5`spurious} spaces.
TeXbook References: 210. Also: 210, 392, 399.

Related Primitives: ifvbox, ifvoid.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

ifhmode Logic
Command
Synopsis: \ifhmode

Description:

    This command is true if TeX is in horizontal or restricted horizontal mode [209].
Example:

     \gdef\checkmode
     {%
          \ifhmode
               \ifinner
                    \def\tmode{RH}% restricted horizontal.
               \else
                    \def\tmode{H}%  horizontal.
               \fi
          \fi
          \ifvmode
               \ifinner
                    \def\tmode{IV}% internal vertical.
               \else
                    \def\tmode{V}%  vertical.
               \fi
          \fi
          \ifmmode
               \ifinner
                    \def\tmode{M}%  math
               \else
                    \def\tmode{DM}% display math
               \fi
          \fi
          {\it mode: \tmode}%
     }
     \checkmode\par% Each example is put in a vbox before it is typeset!
     \vbox{Hello \checkmode\ \hbox{World \checkmode}}
Produces: See typeset version.

Comments:

  • The \checkmode macro identifies each of the six modes.
  • The \ifhbox reference page shows another way to nest if statements.
  • Each of the percent signs in \checkmode is required to keep out spurious\mkindex{space`5`spurious} spaces.
TeXbook References: 209. Also: 209, 363.

Related Primitives: ifmmode, ifvmode, ifinner.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

ifinner Logic
Command
Synopsis: \ifinner

Description:

    This command is true if TeX is in restricted horizontal, internal vertical, or nondisplay math mode [209].
Example:

  1. \def\checkinner
  2. {%
  3.      \ifinner
  4.           \o T% the accent reference page defines \o
  5.      \else
  6.           \o F
  7.      \fi
  8. }
  9. \checkinner\checkinner\checkmode\par% the ifhmode page defines \checkmode
 10. \vbox{\checkinner Hello\checkinner\hbox{\checkinner World \checkmode}}
 11. $ 1+2+3+\ldots+n = {{n(n+1)}\over2}\ \checkinner $\checkinner\checkmode
Produces: See typeset version.

Comments:

  • The first two checks made on line 9 match the first two made on line 10 because, each Example actually takes place inside a vbox. So, lines 9 and 10 start in internal vertical mode, but the first character on each line begins a paragraph which TeX processes in horizontal mode.
  • The \ifhmode reference page shows another example using \ifinner.
TeXbook References: 209. Also: 209.

Related Primitives: ifhmode, ifmmode, ifvmode.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

ifmmode Logic
Command
Synopsis: \ifmmode

Description:

    This command is true if TeX is in math or display math mode [209].
Example:

     \def\L#1%
     {%
          \ifmmode
               \mkern-#1mu\relax
          \else
               \dimen0=0.05em
               \multiply\dimen0 by #1
               \kern-\dimen0\relax
          \fi
     }
     Compare: 1941--1945 with {\it 1941--1945} with {\it 1941--\L11945}\par
     $x^2/2$ vs $x^2\L1/2$ vs $X^2\L2/2$ vs $X^2\L3/2$ vs $X^2\L9/2$
Produces: See typeset version.

Comments:

  • The macro \L may be used in all modes. In math mode, it adds math glue, but in other modes it adds regular glue.
  • I've added many kerns between digits and a hyphen, endash, and emdash for Caslon's roman font. However, I've not adjusted Caslon's italics font. It does look better with a small adjustment.
  • In math mode the \L macro (and a corresponding \R) offer an alternative to Plain TeX's \, and \!.
TeXbook References: 209. Also: 209, 215, 240, 353, 356, 360, 423.

Related Primitives: ifhmode, ifvmode, ifinner.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

ifnum Logic
Command
Synopsis: \ifnum<number1><relation><number2>

Description:

    THIS command compares two integers. The only relations are `<', `>', and `=' which mean less than, greater than, and equal [209]. A <dimen> value may be used as a number. It is converted to scaled points. Also, a <glue> value may be used as a <dimen>. TeX ignores the stretch and shrink components [118]. Each <number> should be one of the following: a) a count register (e.g., \count0); b) a dimen or skip register (each is converted to a number as described above); c) an internal quantity which holds an integer, dimension, or glue (e.g., \year or \vsize); or d) an integer constant (e.g., 1000) [nr].
Example:

  1. \def\mytime%format the time as hh:mm. Always use 2 digits for hh & mm.
  2. {%
  3.   {%
  4.      \count20=\time
  5.      \count22=\count20
  6.      \divide \count20 by 60
  7.      \count21=\count20
  8.      \multiply\count21 by -60
  9.      \advance\count22 by \count21
 10.      \ifnum\count20<10 0\fi% put leading `0' if necessary.
 11.      \the\count20:%
 12.      \ifnum\count22<10 0\fi% put leading `0' if necessary.
 13.      \the\count22
 14.   }%
 15. }
 16. \count20=-100
 17. Time is: \the\time, and count20 = \the\count20.\par
 18. Better time is: \mytime, and count20 = \the\count20.
Produces: See typeset version.

Comments:

  • This shows one way to convert \time, which is the number of minutes after midnight, to military (twenty-four hour) time. The hours are calculated in register 20 and the minutes in register 22. Each register is checked (lines 10 and 12), and an extra 0 is added if necessary so the hours and minutes always have two digits.
  • The grouping done by lines 3 and 14 ensure that the registers used on lines 4-13 will not interfere with other uses of the registers outside of \mytime.
  • Line 16 sets \count20 to -100. It is a value which can never be a valid time. Then line 17 prints \count20 before the call to \mytime, and line 18 prints \count20 after the call. Both values are -100.
  • The \time reference page contains a macro which makes civilian time.
TeXbook References: 209. Also: 208, 209, 218-219.

Related Primitives: ifodd, ifdim.

For Additional Examples, see: advance, day, time, year

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

ifodd Logic
Command
Synopsis: \ifodd<number>

Description:

    THIS command is true if <number> is an odd integer and false if it is an even integer [209]. Since \ifeven is not a primitive control sequence, using it will generate an error unless a macro package which defines it is included [nr].
Example:

  1. . . .
  2. \ifodd\pageno
  3. \else
  4.      \fixpage{}{1}%  Do header and footer cleanup 1.
  5. \fi
  6. \vfill
  7. \eject
  8. \ifodd\pageno
  9. \else
 10.      \fixpage{0}{1}% Do header and footer cleanup 2.
 11.      \hbox to 0pt{}% \eject won't work unless `something' is on the page.
 12.      \vfil
 13.      \eject
 14. \fi
 15. . . .
Produces: See typeset version.

Comments:

  • These lines are from a macro used to end an article in an academic journal. Lines 8-14 ensure the next article starts on a recto page.
  • The header and footer on the last page of the article may be non-standard. Lines 4 and 10 set switches so the correct header and footer is used.
  • If TeX had an \ifeven command, each test would be more readable.
TeXbook References: 209. Also: 207, 209, 416, 418-419.

Related Primitives: ifnum.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

iftrue Logic
Command
Synopsis: \iftrue

Description:

    THIS is a conditional which is always true. Thus, any text following an accompanying \else will never be used [210]. The command is often used with \mark to set up running headers for the pages of a book or an index [260].
Example:

  1. . . .
  2. % the next line goes in a recto (odd) page header.
  3.      \setbox1=\hbox{{\selffamily AC\it\iftrue\botmark\fi}}%
  4. . . .
  5. %The next lines are from the macro that makes the reference page for a CS.
  6. %We have: \def\CScs{ControlSequence}, e.g., \def\CScs{iftrue}
  7. %\box0 holds everything through the Synopsis line.
  8. %
  9.      \mark{\currentcs\noexpand\else\CScs}
 10. . . . % do \eject unless following \box0 will fit on current page.
 11. %       The \ifdim reference page shows this test.
 12.      \unvbox0%
 13.      \mark{\CScs\noexpand\else\CScs}
 14. . . . %typeset the rest of the page.
 15.      \let\currentcs=\CScs%
 16. . . .
Produces: See typeset version.

Comments:

  • It is tricky to get the correct control sequence on the header line of these reference pages. Two things are required [260-261].
  • First, a special mark is made before and after the start of each control sequence (lines 9 and 13). Each mark contains two options separated by `\noexpand\else'.
  • Second, each header routine uses either \iftrue or \iffalse and the appropriate mark (\botmark, \firstmark, or \topmark).
  • Some thought and possibly a review of the mark commands should show that line 3 will select the appropriate control sequence for odd pages.
TeXbook References: 210-211. Also: 210, 211, 260-261, 348.

Related Primitives: iffalse.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

ifvbox Logic
Command
Synopsis: \ifvbox<8-bit number>

Description:

    THIS command is true if \box<number> contains a vbox. The number must be a valid box register (i.e., from 0 to 255) [210].
Example:

  1. \def\checkvbox#1%
  2. {%
  3.      \ifvbox#1
  4.           \o T%
  5.      \else
  6.           \o F%
  7.      \fi
  8. }
  9. \setbox1=\vbox{Twenty One}
 10. \setbox2=\vbox{Twenty Two}
 11. \checkvbox1---\checkvbox2\par
 12. \copy1\box2
 13. \checkvbox1---\checkvbox2
Produces: See typeset version.

Comments:

  • Line 11 shows that each box is in fact a vbox.
  • After line 12, box2 will be void, and line 13 shows that box2 is not a vbox.
  • The \ifhbox reference page shows another example of \ifvbox.
TeXbook References: 210. Also: 210.

Related Primitives: ifhbox, ifvoid.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

ifvmode Logic
Command
Synopsis: \ifvmode

Description:

    This command is true if TeX is in vertical or internal vertical mode [209].
Example:

  1. \checkmode\par% the ifhmode reference page defines \checkmode
  2. \vbox{\checkmode\ Hello \checkmode\ \hbox{World \checkmode}}
Produces: See typeset version.

Comments:

  • The \checkmode on line 1 is in IV mode because each example is put in a vbox before it is typeset.
TeXbook References: 209. Also: 209.

Related Primitives: ifhmode, ifmmode, ifinner.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

ifvoid Logic
Command
Synopsis: \ifvoid<8-bit number>

Description:

    THIS command is true if \box<number> is void. The number must be a valid box register (i.e., from 0 to 255) [210].
Example:

  1. \def\checkvoid#1%
  2. {%
  3.      \ifvoid#1
  4.           V%
  5.      \else
  6.           N%
  7.      \fi
  8. }
  9. \setbox1=\hbox{}
 10. \setbox2=\hbox{Twenty Two}
 11. \checkvoid1---\checkvoid2\par
 12. Where is box 1? \copy1---\box2\par
 13. \checkvoid1---\checkvoid2
Produces: See typeset version.

Comments:

  • Line 11 shows that initially neither box is void even though box1 is empty.
  • After line 12 box2 will be void, and line 13 shows that is the case. However, box1 is still not void.
  • The \ifhbox reference page has another example of \ifvoid.
TeXbook References: 210. Also: 210, 256.

Related Primitives: ifhbox, ifvbox.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

ifx Logic
Command
Synopsis: \ifx<token1><token2>

Description:

    WHEN evaluating \ifx, TeX does not expand the tokens which follow the \ifx. Instead, the comparison is true if a) both tokens are characters with the same character and category codes; or b) both tokens represent the same TeX primitive, \font, \chardef, \countdef, or other internal quantity; or c) both tokens are macros which have: the same status with respect to \long and \outer; the same parameters; and the same top-level expansion [210].
Example:

  1. \def\tmacro#1%
  2. {%
  3.      \def\temptyA{#1}% I use temptyB, C, ... for parameters 2, 3, ...
  4.      \ifx\temptyA\empty
  5.           DV% default value.
  6.      \else
  7.           #1%
  8.      \fi
  9.      --\par
 10. }
 11. \tmacro{Just a test}
 12. \tmacro{- Whoops!}
 13. \tmacro{}
Produces: See typeset version.

Comments:

  • It is common to write a TeX macro with several parameters and then design the macro so it works one way if a particular parameter is present and a second way if the parameter is absent.
  • This example shows one way to check for a missing or unused parameter. The \if reference page shows another way, but that way does not always work. This one does!
  • Line 3 defines a special control sequence which holds the parameter. When the parameter is needed, \ifx compares the special cs to \empty which Plain TeX defines as: `\def\empty{}'.
TeXbook References: 210. Also: 210, 215, 307, 384, 375-377, 418.

Related Primitives: if, ifcat.

For Additional Examples, see: endinput

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

ignorespaces Paragraph
Command
Synopsis: \ignorespaces<optional spaces>

Description:

    AFTER \ignorespaces TeX reads and expands tokens and does nothing until it reaches a token which is not a space [279].
TeXbook References: 279. Also: 279, 333, 355, 424.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

immediate File I/O
Command
Synopsis: \immediate<write or openout or closeout>

Description:

    NORMALLY, the output commands \write, \openout, and \closeout are placed in a whatsit item on the current list. When the list shows up in a box during a \shipout operation, the whatsit item is expanded and the actual write, open, or close takes place. There are times when execution of an output command should not be deferred. It should occur at the time TeX encounters it in a document. If \immediate comes just before one of the output commands, the command occurs without delay (i.e., immediately) [227].
Example:

     \immediate\openout\twaux=junkjunk.tex\relax
     \immediate\write\twaux{{\noexpand\bf byebye}\ World}
     \immediate\closeout\twaux
Produces: See typeset version.

Comments:

  • This example is the same as the example on the \closeout reference page except each of the three lines begins with \immediate.
  • The macros used to format these pages put the output of each example in a box. Then, if the box has a positive height, the box is typeset. In the \closeout example the box contains the three whatsits\mkindex{whatsit`5`file I/O}, but its height is zero. So, it is never added to the current page and hense the three commands are lost.
  • This example works completely differently. When TeX is building the box and encounters one of the \immediate commands, it does not make a whatsit. Instead it just does the following open, write, or close. The resulting box is empty, but the commands get done.
TeXbook References: 227. Also: 226-228, 280, 422, 423.

Related Primitives: write, openout, closeout.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

indent Paragraph
Command
Synopsis: \indent

Description:

    NORMALLY, TeX needs no help in starting a new paragraph, but occasionally it does. The \indent command causes TeX to switch from vertical or internal vertical mode to horizontal mode. Also, it adds an empty box to the new horizontal list [86]. The width of the box is the value of \parindent at the time the box is added to the list [101]. If TeX is already in horizontal or math mode, \indent adds an empty box whose width is \parindent to the current list [86] and sets the spacefactor to 1000 [286].
Example:

     \parindent=2pc
     \indent |\indent| provides one way to start a new paragraph.\par
     \indent Also, it can \indent add space anywhere in the paragraph.\par
     \noindent |\noindent| also starts a paragraph, but it does not do the indent.\par
     Finally, |\par| provides a way to end a paragraph that is not followed by a blank line.
Produces: See typeset version.

Comments:

  • The example, together with what it produces, illustrates: \indent, \noindent, and \par.
TeXbook References: 86, 101. Also: 86, 94, 101, 263, 282, 286, 291, 355.

Related Primitives: parindent, noindent.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

input File I/O
Command
Synopsis: \input<file name>

Description:

    WHEN TeX encounters this command, it prepares to read from the specified file before continuing with the current source file [214]. Most TeX implementations add the extension .tex to the file name if the name does not have an extension [217]. If TeX can't locate the file, it writes a message to the log file and on the terminal and interrupts processing so a new name can be entered [nr].
Example:

     \input a % a.tex holds the line: \input c
     \input b % b.tex holds the line: \input c
     % c.tex holds the line: \newread\tr
Produces: See typeset version.

Comments:

  • The above lines illustrate a problem that will be familiar to programmers.
  • A complex document may require many formatting files, and some of those files may in turn require others. If a file is loaded twice, it may allocate resources more than once.
  • In the example c.tex is loaded twice, and each time a new \tr is allocated. Since there are only 16 input streams, it would be easy to allocate all of them even though only 2 or 3 are actually needed.
  • The \endinput reference page shows how to avoid the above problem.
TeXbook References: 199, 214. Also: 7, 9, 25-27, 47, 199, 214, 217, 380, 382-383, 403, 422.

Related Primitives: endinput, inputlineno.

For Additional Examples, see: endinput, openin

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

inputlineno File I/O
Internal Quantity
Synopsis: \inputlineno

Description:

    This quantity holds the line number of the current line in the current source file[*304 TeX: The Program].
Example:

     The current line number is: \the\inputlineno.
Produces: See typeset version.

TeXbook References: 214. Also: 214, 271.

Related Primitives: input.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

insert Inserts
Command
Synopsis: \insert<8-bit number>{<vertical mode material>}

Description:

    MOST of the time TeX works sequentially typesetting material across lines and down the page. However, there are times when material needs to be repositioned. For example, footnotes appear at the bottom of a page; endnotes appear at the end of an article or chapter; and a figure may float to the top of the current or the next page. Insertions provide such flexibility. There are 255 classes of insertions: \insert0 to \insert254. Plain TeX provides a \newinsert command. It or something similar should be used to define a new class because each class requires a \box, \count, \dimen, and \skip register and all the registers must use the same number used by the class. TeX keeps all insertions of the same class together in the order they were made. For a particular class, say \insert100, \box100 is made available to the output routine and holds the insertions made to \insert100; \dimen100 holds the maximum height plus depth allowed for \box100 on any single page; \skip100 is the amount of extra space the output routine adds when it positions \box100 on the page; and \count100 holds the magnification factor used with insertions in \insert100. For example, let x be the height plus depth of some \insert100 and let y be the actual change in \pagetotal of the insertions. Then, \count100 = 1000(y/x). For footnotes y is usually x, and \count100 = 1000. But for endnotes or material destined for the margin, y = 0 as does \count100. The actual steps used to prepare \box100 are described on pages 123-124 of The TeXbook. If there is more material in \insert100 than will fit on the current page, part of the material is split (using \vsplit, \splittopskip, and \splitmaxdepth) and placed in \box100. The rest of the material is saved for the next page [122-123]. An insertion will appear on a page only if it appears on TeX's main vertical list [281]. Since \box255 is reserved for use by TeX and the output routine, \insert255 is not allowed [280].
Example:

  1. % Footnotes
  2. \newinsert\footins  % create Footnotes insertions class.
  3. \count\footins=1000 % footnote magnification factor (1 to 1)
  4. \dimen\footins=\vsize % maximum footnotes per page
  5. \skip\footins=12pt plus 24pt% space added when footnote is present
  6. % End Notes
  7. \newinsert\notes %create Endnotes insertions class.
  8. \count\notes=0 % endnotes don't appear on current page.
  9. \dimen\notes=\maxdimen
 10. \skip\notes=0pt % no extra space on current page for endnotes.
Produces: See typeset version.

Comments:

  • Insertions appear complicated because they require three separate steps to work:
  • First, the insertion class is created and the associated count, dimen, and skip registers are initialized. Lines 1-5 do this for footins, and lines 6-10 do it for notes.
  • Second, one or more special macros are written which prepare the actual insertion. This is where the \insert command is used (e.g., \insert\footins or \insert\notes).
  • Third, the output routine is modified so it queries the appropriate box register (e.g., \box\footins or \box\notes) and positions the box on the current page.
TeXbook References: 122-125. Also: 95, 122-125, 259, 280-281, 363, 416, 424, 454.

Related Primitives: holdinginserts, floatingpenalty, insertpenalties, vsplit.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

insertpenalties Inserts
Internal Quantity
Synopsis: \insertpenalties

Description:

    THIS quantity holds two different values. In the ouput routine \insertpenalties holds the total number of held-over insertions. For each class of insertions this includes the unused part of a split insertion and all other insertions which don't appear on the current page [125 and 254]. In the page-making routine \insertpenalties holds the total of the \floatingpenalty for each unsplit insertion which is carried over to the next page [111 and 123].
TeXbook References: 123-125, 254. Also: 111, 114, 123-125, 214, 254, 256, 271.

Related Primitives: floatingpenalty, insert.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

interlinepenalty Penalties (Page)
0 (100 for footnotes) * Parameter (integer)
Synopsis: \interlinepenalty

Description:

    AFTER TeX breaks a paragraph into lines, it moves each line to the containing vertical list. TeX adds \interlinepenalty to the penalties inserted immediately after every line for each line except the last one [104].
TeXbook References: 104. Also: 104, 272, 363, 406, 419.

Related Primitives: clubpenalty, widowpenalty, brokenpenalty, linepenalty.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

jobname Job
Command
Synopsis: \jobname

Description:

    IF TeX is processing a document whose name is fname.tex, then \jobname expands to fname [213]. Each character in the expansion receives category code 12 (other), except for spaces which receive code 10 (space) [214].
Example:

  1. \def\basedir{\string~/doc/trm/}% Unfortunately, my version of TeX
  2. \def\myfilenameA%                doesn't provide the directory.
  3. {%
  4.   \bgroup
  5.      \selffamily AG
  6.      \setbox0=\hbox
  7.      {%
  8.           \ifx\basedir\empty% Traps potential bug if \basedir is not defined
  9.                \string~/.../
 10.           \else
 11.                \basedir
 12.           \fi
 13.           \jobname.tex%
 14.      }%
 15.      \setbox1=\hbox
 16.      {
 17.           \mydatetime% see reference pages for: \month & \ifnum.
 18.      }%
 19.      \hbox to \pagewidthB
 20.      {%
 21.           \box0
 22.           \hfil
 23.           -- \number\pageno\ --%
 24.           \hfil
 25.           \box1
 26.      }%
 27.   \egroup
 28. }
 29. The document name is: \jobname\par
 30. \myfilenameA
Produces: See typeset version.

Comments:

  • Line 29 shows a simple use of \jobname.
  • The macro in lines 2-28 prepares a line which might be placed in a header or footer routine. The line lists the TeX file name and directory, the page, and the date and time the file was typeset.
  • Line 1 shows an example of \basedir which provides the directory name.
  • The test on lines 8-12 allows \myfilenameA to work even if \basedir is not defined.
TeXbook References: 213. Also: 213, 214, 336.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

kern Kern
Command
Synopsis: \kern<dimen>

Description:

    THIS command adds a kern item with the specified dimension to the current list [280]. A \kern specifies vertical spacing in vertical mode and horizontal spacing in horizontal [87] or math [168] mode. Also, a kern is similar to glue except it cannot stretch or shrink. TeX will not break a line at a kern, unless the kern is immediately followed by glue [75]. The hyphenation algorithm distinguishes between implicit kern items (i.e., kerns inserted by TeX because of information stored with the current font) [454] and explicit kern items (i.e., ones added with \kern) [306].
Example:

  1. A kern may be used \kern0.25in anywhere.\par
  2. \kern0.25in However, the results may be unexpected if the mode is wrong.\par
  3. \noindent\kern0.25in See what I mean?
Produces: See typeset version.

Comments:

  • The \kern on line 1 is in the middle of a paragraph and so adds horizontal space.
  • The \par at the end of line 1 ends the paragraph. Thus, the kern at the start of line 2 is in vertical mode and so adds vertical space.
  • The \noindent at the start of line 3 begins a new paragraph so the following \kern adds horizontal space.
TeXbook References: 280. Also: 10, 40, 66, 75, 87, 168, 256, 263, 280, 306, 389, 394-395, 416, 424, 454-455.

Related Primitives: hskip, vskip, mkern.

For Additional Examples, see: ifmmode

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

language Hyphenation
0 * Parameter (integer)
Synopsis: \language=<number>

Description:

    TEX can store hyphenation patterns and exceptions for up to 256 different languages. Then, it can apply an appropriate set of hyphenation rules for each paragraph or part of a paragraph in a ms. When TeX begins a new paragraph, it sets the current language to \language. Just before it adds each new character to the paragraph in unrestricted horizontal mode, it compares the current language to \language. If they are different, TeX : a) changes the current language to \language; b) inserts a whatsit\mkindex{whatsit`5`language} containing the new language and the values of \lefthyphenmin and \righthyphenmin; and c) inserts the character. The \setlanguage command should be used to change languages in restricted horizontal mode (i.e., inside an \hbox). If <number> is less than 0 or greater than 255, 0 is used [455]. Plain TeX has a \newlanguage command which may be used to allocate numbers for languages [347]. Changes made to \language are local to the group containing the change [nr].
Example:

  1. {\language254\hyphenation{am-ong}}
  2. {\language255\hyphenation{I-nquisitor}}
  3. \def\tlangX{\lefthyphenmin=2\righthyphenmin=1\language254}
  4. \def\tlangY{\lefthyphenmin=1\righthyphenmin=1\language255}
  5. \def\tstoryA{\tlangX There are cries, sobs, confusion among the
  6. people, and at that moment the cardinal himself, the Grand Inquisitor,
  7. passes by the cathedral. He is an old man . . .}
  8. \def\tstoryB{\tlangX There are cries, sobs, confusion among the
  9. people, and at that moment the cardinal himself, the Grand \tlangY
 10. Inquisitor, passes by the cathedral. He is an old man . . .}
 11. \count0=\the\language
 12. \setbox0=\vbox{\hsize=2.25in \tstoryA}
 13. \setbox1=\vbox{\hsize=2.25in\language255 \tstoryB}
 14. \hbox to \hsize{\box0\hfill\box1}
 15. The values are: \the\count0\ and \the\language.
Produces: See typeset version.

Comments:

  • Lines 1-2 of this example add hyphenated words to the exception dictionaries for languages 254 and 255.
  • Lines 3-4 define a control sequence for each language which sets \lefthyphenmin and \righthyphenmin and switches to the language.
  • Line 11 typesets \tstoryA using \language254, and line 12 typesets \tstoryB using both languages.
  • Lines 11 and 15 show the change made to \language on line 13 are local.
TeXbook References: 455. Also: 273, 346-347, 455.

Related Primitives: setlanguage, hyphenation, patterns, lefthyphenmin, righthyphenmin.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

lastbox Box
Command
Synopsis: \lastbox

Description:

    THIS command is used with the other last commands to step through the items in a list. If the last item on the current horizontal or internal vertical list is an \hbox, \vbox, or \vtop, \lastbox becomes the box and removes it from the list; otherwise \lastbox is void. The command may not be used on the main vertical list or in math mode [222].
Example:

  1. \setbox0=\hbox{Box 0}
  2. \setbox1=\hbox{Box 1}
  3. \setbox2=\hbox{Box 2}
  4. \setbox3=\hbox{Box 3}
  5. \setbox4=\hbox{Box 4}
  6. \setbox5=\vtop
  7. {
  8.      \copy0
  9.      \copy1
 10.      \copy2
 11.      \copy3
 12.      \copy4
 13.      \vskip 2pt
 14.      \global\setbox6=\lastbox
 15. }
 16. \setbox7=\vtop
 17. {
 18.      \copy0
 19.      \copy1
 20.      \copy2
 21.      \copy3
 22.      \copy4
 23.      \global\setbox8=\lastbox
 24.      \vskip 2pt
 25. }
 26. \hbox{\box5\hskip 20pt\box7}
 27. \halign{%
 28. &\quad#&#\hfil\cr
 29. &\bf Box&&\bf Width&&\bf Contents\cr
 30. &6&&\the\wd6&&\copy6\cr
 31. &8&&\the\wd8&&\copy8\cr
 32. }
Produces: See typeset version.

Comments:

  • The \lastbox command in \box5 is void because the previous item in the box is glue (lines 13-14).
  • The \lastbox command in \box7 is a copy of \box4. Also, the copy of \box4 in \box7 is removed by line 23.
  • The results of the \halign on lines 27-32 verify the previous two statements.
TeXbook References: 222. Also: 222, 278, 354, 392, 398, 399.

Related Primitives: lastkern, lastpenalty, lastskip.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

lastkern Kern
Internal Quantity
Synopsis: \lastkern

Description:

    IF the last item on the current list is a kern, \lastkern is the amount of that kern; otherwise \lastkern is 0.0pt. The kern item itself is not removed from the list by \lastkern [214]. The \unkern command does that [280].
Example:

     \def\kernbreakup
     {%
          \ifdim\lastkern=0pt
               lastkern is: 0pt.
          \else
               \dimen0=\lastkern
               lastkern is: \the\dimen0
          \fi
     }
     \def\mkbox#1%
     {%
          \setbox0=\vbox{\kern 6pt\hbox{Hello}\kern #1}%
          \setbox1=\vbox{\unvcopy0\kernbreakup}%
          \box1
     }
     \mkbox{4pt}
Produces: See typeset version.

Comments:

  • The \kernbreakup macro is similar to lines used to remove a kern from a box in a breakup macro.
  • The \mkbox macro makes a simple vbox whose last component is a kern.
  • The call to \mkbox correctly identifies the kern.
TeXbook References: 214. Also: 214, 271.

Related Primitives: unkern, lastbox, lastpenalty, lastskip.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

lastpenalty Penalties
Internal Quantity
Synopsis: \lastpenalty

Description:

    IF the final item on the current list is a penalty, \lastpenalty has that value; otherwise \lastpenalty is 0. The penalty item itself is not removed from the list by \lastpenalty [214]. The \unpenalty command does that [280].
Example:

  1. \def\penaltybreakup
  2. {%
  3.      \setbox1=\hbox{\unhcopy0\global\count1=\lastpenalty}%
  4.      \setbox2=\hbox
  5.      {%
  6.           \unhbox2
  7.           \ifnum\count1=0
  8.                WHOOPS: %
  9.           \else
 10.                lastpenalty is: \the\count1 \ %
 11.           \fi
 12.      }%
 13. }
 14. \def\mkbox#1#2%
 15. {%
 16.      \setbox0=\hbox{#2\penalty #1}%
 17.      \penaltybreakup
 18.      \box0 \ %
 19. }
 20. \box2
 21. \noindent\mkbox{100}{Hello}%
 22. \mkbox{10\kern12pt}{Brave New}%
 23. \mkbox{0}{World}\par
 24. \box2
Produces: See typeset version.

Comments:

  • The \penaltybreakup macro is similar to lines used to remove a penalty from a box in a breakup macro.
  • The \mkbox macro makes a simple hbox whose last component is a penalty.
  • The first call to \mkbox correctly identifies the penalty (line 21). The second call does not, but that is not a surprise since a kern follows the penalty (line 22). The third call makes a penalty that is 0 (\showbox verifies this), but \lastpenalty is unable to distinguish this real but zero penalty from the kern on line 22.
TeXbook References: 214. Also: 214, 271.

Related Primitives: unpenalty, lastbox, lastkern, lastskip.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

lastskip Glue
Internal Quantity
Synopsis: \lastskip

Description:

    IF the last item on the current list is glue or muglue, \lastskip is the amount of that glue; otherwise \lastskip is 0.0pt. The glue item itself is not removed from the list by \lastskip [214]. The \unskip command does that [280]. Unfortunately, there is not an `if...' test which compares two glue values. That makes it difficult to breakup boxes containing glue with stretchable or shrinkable compontents [nr].
Example:

     \def\skipbreakup
     {%
          \skip0=\lastskip
          \ifdim\skip0=0pt
               WHOOPS: lastskip is: \the\skip0
          \else
               lastskip is: \the\skip0
          \fi
     }
     \def\mkbox#1%
     {%
          \setbox0=\vbox{\kern 6pt\hbox{Hello}\vskip #1}%
          \setbox1=\vbox{\unvcopy0\skipbreakup}%
          \box1
     }
     \mkbox{4pt plus 3pt minus 2pt}
     \mkbox{0pt plus 3pt minus 2pt}
Produces: See typeset version.

Comments:

  • The \skipbreakup macro is similar to lines used to remove glue from a box in a breakup macro.
  • The \mkbox macro makes a simple vbox whose last component is glue.
  • The first call to \mkbox correctly identifies the glue. The second call does not. That is because the \ifdim test does not consider the stretchable and shrinkable components of glue.
TeXbook References: 214. Also: 214, 223, 271, 392.

Related Primitives: unskip, lastbox, lastkern, lastpenalty.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

lccode Character
Internal Quantity
Synopsis: \lccode<8-bit number>

Description:

    THIS quantity is used by \lowercase to convert a character to its lowercase equivalent [41]. INITEX sets `\lccode`A=`a' and `\lccode`a=`a'. It makes similar assignments for all other letters. Finally, it makes the \lccode of all nonletters zero [345]. Words added to the hyphenation dictionary are converted to lowercase. So, each nonhyphen character in the word must have a nonzero \lccode [452].
TeXbook References: 41. Also: 41, 214, 271, 345, 452-454.

Related Primitives: uccode, catcode, sfcode, lowercase, hyphenation.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

leaders Box
Command
Synopsis: \leaders<box or rule><glue>

Description:

    LEADERS consist of a box and some glue. Copies of the box are used to fill the space specified by the glue [223]. Leaders made with \leaders are aligned [224]. A rule may be used in place of a box. This allows \hrule to make a horizontal line in horizontal mode [224-225].
Example:

     \def\sampletocB#1#2%
     {%
          \hbox to 3in
          {%
               #1% 0.0625 makes 16 dots per inch.
               \leaders
                    \hbox to 0.0625in{\hfil.\hfil}
                    \hfill
               \hbox to 0.25in{\hfil #2}%
           }
     }
     \def\sampleheader#1%
     {%
          \hbox to 3in
          {%
               {\it #1}%
               \kern3pt
               \leaders
                    \hrule height 0.25pt
                    \hfill
          }
     }
     \sampletocB{}{100}% Count the dots. There are 44.
     \sampletocB{Strangers and Brothers}{116}
     \sampletocB{The Age of Reason}{178}
     \sampleheader{Strangers And Brothers}
     \sampleheader{The Age of Reason}
Produces: See typeset version.

Comments:

  • This illustrates two common uses of leaders: the table of contents and page headers.
TeXbook References: 223-225, 281, 285. Also: 95, 110, 223, 224, 225, 357, 392-394.

Related Primitives: cleaders, xleaders, hrule.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

left Math
Command
Synopsis: \left<delim1><subformula>\right<delim2>

Description:

    THIS command begins a construction which has a delimiter on either side of a subformula. TeX computes how large the delimiter should be based on what is in the subformula. There are three main rules for using \left: a) there must be a matching \right command; b) the `\left ... \right' pair must occur in the same group; and c) the resulting subformula must be typeset on 1 line. However, the delimiters need not match (e.g., `(...]' is fine). Also, if a `.' is used for either delimiter, it will be omitted. TeX makes the delimiter just big enough to cover the subformula. While that is what is needed most of the time, there are instances when TeX makes an outer delimiter that is too small [148-149]. Also, there are times when `\left ... \right' puts more space around the subformula than one of Plain TeX's \big commands puts [171].
Example:

  1. ${\bigl||x| - |y|\bigr|} = {\left||x| - |y|\right|}$\par
  2. Let $p$ be any odd prime which does not divide $a(a^2 - 1)$. We take
  3. $$m = {a^{2p} - 1 \over a^2 - 1} =
  4.      \left({a^p - 1 \over a - 1}\right)
  5.      \left({a^p + 1 \over a + 1}\right),\leqno(6.9.2)$$
  6. so that $m$ is clearly composite. Now \dots
Produces: See typeset version.

Comments:

  • Line 1 shows an example where the hand selection of \bigl looks better than what is constructed by \left.
  • Lines 4-5 show a more typical use of \left, and everything looks fine.
TeXbook References: 148-149. Also: 148-150, 155-157, 171, 196, 292, 437.

Related Primitives: right, delcode, delimiter.

For Additional Examples, see: delimiterfactor, nulldelimiterspace, vcenter

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

lefthyphenmin Hyphenation
2 * Parameter (integer)
Synopsis: \lefthyphenmin=<number>

Description:

    THIS parameter holds the minimum number of characters that must appear at the beginning of a hyphenated word (i.e., before the `-'). In particular, TeX will not hyphenate words with fewer than \lefthyphenmin + \righthyphenmin characters [454]. The whatsit\mkindex{whatsit`5`language} made by a change to \language includes the current value of \lefthyphenmin [455]. Changes made to \lefthyphenmin are local to the group containing the change [nr].
Example:

  1. \def\tstoryA{There are cries, sobs, confusion among the people, and at
  2. that moment the cardinal himself, the Grand Inquisitor, passes by the
  3. cathedral. He is an old man . . .}
  4. {\language255\hyphenation{m-oment}}
  5. \count0=\lefthyphenmin
  6. \setbox0=\vbox{\hsize=2.25in\language255 \tstoryA}
  7. \setbox1=\vbox{\hsize=2.25in\language255\lefthyphenmin=1 \tstoryA}
  8. \hbox to \hsize{\box0\hfill\box1}
  9. The values are: \the\count0\ and \the\lefthyphenmin.
Produces: See typeset version.

Comments:

  • This example adds a non-standard hyphenation of moment to language 255's exception dictionary.
  • Line 6 typesets \tstoryA using the default value of \lefthyphenmin.
  • Line 7 typesets the same material with the same language but with a smaller value of \lefthyphenmin.
  • Lines 5, 8, and 9 show the change made to \lefthyphenmin on line 7 is local.
TeXbook References: 273, 454. Also: 273, 364, 454, 455.

Related Primitives: righthyphenmin, language.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

leftskip Paragraph
0pt * Parameter (glue)
Synopsis: \leftskip=<glue>

Description:

    THIS parameter holds glue which TeX inserts on the left of every line in a paragraph [100]. The value used is the one current when the paragraph ends [101].
Example:

     \parindent=1.5pc
     \tstory\par% The \adjdemerits reference page holds the definition of \tstory
     \vskip3pt
     {\leftskip=2pc
     \rightskip=\leftskip
     \noindent\tstory\par}
Produces: See typeset version.

Comments:

  • The first paragraph is indented and uses the \hsize used on these pages.
  • The second paragraph is not indented and has 2 picas placed on the left and right of each line.
TeXbook References: 100-101. Also: 100-101, 274, 317, 407, 419.

Related Primitives: rightskip, parindent, parfillskip.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

leqno Math
Command
Synopsis: \leqno<formula>

Description:

    THIS command puts an equation number at the left-hand margin [186]. It may only be used in display math mode. TeX processes the material for the number as follows: a) it enters a new level of grouping and begins non-display math mode; b) it adds the \everymath tokens to the new math list; c) it adds everything between the \leqno command and the $$ which ends the display to the math list; d) it converts the math list to a horizontal list which it puts in an hbox. The resulting hbox becomes the equation number [293]. TeX tries the following strategies as it positions the equation number and the display on a line: a) center the display and then place the equation number at the left margin; b) place the equation number at the left margin and then position the display in the remaining space; [187] c) if the display and the equation number are wider than \displaywidth or if the equation number has zero width, place the equation number at the left margin on a line by itself; add an infinite penalty; and center the display on the following line. The infinite penalty prevents TeX from typesetting the equation number on one page and the display on the following page [188-189].
Example:

  1. \def\tfn#1%
  2. {%
  3.      $$ u_{-n} = -(xy)^{-n}u_n = (-1)^{n-1}u_n{,}\qquad v_{-n} =
  4.         (-1)^nv_n.#1
  5.      $$%
  6. }
  7. \tfn{\eqno\llap{(10.14.5)}}
  8. \tfn{\leqno\rlap{(10.14.6)}}
Produces: See typeset version.

Comments:

  • This example uses Plain TeX's \llap and \rlap to make the width of the box holding the equation number be zero. That causes TeX to typeset the equation number on a line by itself and to put an infinite penalty in the vertical list between the equation number and the display [189]. The penalty prevents the two items from appearing on different pages.
  • Note line 4. Both left and right equation numbers are typed at the end of the display.
TeXbook References: 187, 293. Also: 187, 189, 293, 375-376.

Related Primitives: eqno.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

let Macro
Command
Synopsis: \let<control sequence>=<token>

Description:

    THIS command provides a second way (the various \def's provide the first) for a control sequence to acquire a new meaning. The command may be used to interchange the meaning of two control sequences [206]. The statement `\let\a=\b' gives \a the current meaning of \b. If \b changes after the assignment is made, \a does not change. Also, \a is not a macro. So, TeX does not expand it in situations where macros are expanded [207]. Expansion of tokens is suppressed when TeX is reading the argument token for \let [215].
Example:

  1. \def\th{-\hskip10pt-}
  2. \def\ta{Hello\th}
  3. \def\tb{\th World }
  4. 1. \ta\tb\par
  5. \begingroup
  6. \let\tc=\ta
  7. \let\ta=\tb
  8. \let\tb=\tc
  9. 2. \ta\tb\par
 10. \endgroup
 11. 3. \ta\tb\par
Produces: See typeset version.

Comments:

  • Lines 6-8 interchange the meaning of \ta and \tb.
  • Line 11 shows that, when the group ends, everything reverts to its pre-group state.
TeXbook References: 206. Also: 206-207, 215, 277, 307, 309, 329, 352, 376.

Related Primitives: def, futurelet.

For Additional Examples, see: endinput, futurelet, iffalse, mathchardef

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

limits Math
Command
Synopsis: \limits

Description:

    SEVERAL math symbols such as summation and integration often appear with subformulas as subscripts and superscripts. The subformulas may be typeset either above and below or to the right of the symbol. Normal mathematical conventions use the first method for most displayed expressions and the second for most in-line expressions. TeX's conventions use the first method in display style and the second method in text style. TeX has three commands which change these conventions: \limits always uses the first method; \nolimits always uses the second method; and \displaylimits uses TeX's normal conventions. If two or more of these commands follow each other, the last one controls how the expression is typeset [144]. Each of these commands must follow a large operator (class 1). Otherwise, TeX generates an error [292].
Example:

  1. \mathchardef\Intop="1352
  2. \mathchardef\Sum="1350
  3. \def\tint{\Intop\nolimits}
  4. \def\tsum{\Sum}
  5. \def\tf#1#2#3%
  6. {%
  7.      $$\hbox{$#2_0^1 3x^2 = x^3]_0^1 = 1$}%
  8.           \hbox{ and $#3^\infty_{n=0}{1\over2^n} = 2$}%
  9.           \kern2pc
 10.           #2_0^1 3x^2 = x^3\Bigr]_0^1 = 1
 11.           \kern2pc
 12.           #3^\infty_{n=0}{1\over2^n} = 2
 13.           \kern2pc
 14.           \leqno{#1.}
 15.      $$
 16. }
 17. \tf 1{\tint}{\tsum}
 18. \tf 2{\tint\limits}{\tsum\limits}
Produces: See typeset version.

Comments:

  • Lines 1-4 are adapted from Plain TeX [358]. They setup symbols for summation and integration. The integral symbol includes \nolimits because that is how integrals normally appear.
  • Lines 5-16 define a macro which mixes in-line math with display math.
  • Line 17 calls \tf using \tint and \tsum. This typesets each expression as it was intended to be typeset.
  • Line 18 makes a similar call only each symbol is followed by \limits. This changes the form of the first three expressions.
  • I tried the `]' on line 10 in two ways (see the \nolimits reference page for the second way) but prefer the way shown here.
TeXbook References: 144. Also: 144, 159, 292, 358, 443.

Related Primitives: nolimits, displaylimits, textstyle, displaystyle.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

linepenalty Penalties (Paragraph)
10 * Parameter (integer)
Synopsis: \linepenalty

Description:

    WHEN TeX is working to break a paragraph into lines, it adds \linepenalty to each potential line's badness in its calculation of the line's demerits. Increasing this parameter causes TeX to try and use fewer lines for the paragraph [98].
Example:

     \def\tstoryA{There are cries, sobs, confusion among the people, and at that moment the cardinal himself, the Grand Inquisitor, passes by the cathedral. He is an old man}
     \hsize=1.9in
     \setbox0=\vtop{\linepenalty=-1000\tstoryA\par\vskip0.5\baselineskip
     \linepenalty=-5000\tstoryA\par}
     \setbox1=\vtop{\linepenalty=5000\tstoryA\par\vskip0.5\baselineskip
     \linepenalty=10000\tstoryA\par}
     \hbox{\box0\hskip1in\box1}
Produces: See typeset version.

Comments:

  • This example is typical of the author's experiments with \linepenalty.
  • The top two paragraphs are typeset using -1000 and 5000 for \linepenalty. Identical results are obtined for 0, 10, and other values between -1000 and 5000.
  • The bottom left paragraph uses -5000 for \linepenalty. This value allows lines with large badness to have a small number of demerits; the result is a horrible first line.
  • The bottom right paragraph uses 10,000 for \linepenalty. Such a large value means badness has little influence on the selection of line breaks; this also results in a horrible line.
  • The primitive command \looseness is intended to typeset a paragraph with fewer or more than the optimum number of lines.
TeXbook References: 98. Also: 98, 272, 314, 316, 348.

Related Primitives: badness, looseness, interlinepenalty.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

lineskip Paragraph
1pt * Parameter (glue)
Synopsis: \lineskip=<glue>

Description:

    IF the glue specified by \baselineskip brings two adjacent boxes in a vertical list closer together than \lineskiplimit, then \lineskip glue is placed between the boxes [78].
Example:

     \parindent=1.5pc\hsize=4.75in
     \baselineskip=9pt
     \lineskip=0pt
     \lineskiplimit=0pt
     \tstory\par% The \adjdemerits reference page holds the definition of \tstory
     \lineskip=2pt
     \lineskiplimit=0pt
     \tstory\par
Produces: See typeset version.

Comments:

  • The first paragraph is set 10/9 (10pt type on 9pts of space). The lines of type touch each other and in places are further that 9 points apart.
  • The second paragraph is also set 10/9. Careful measurement shows the baselines are not uniformally spaced but vary from 11 to 12 points.
TeXbook References: 78-80. Also: 78-80, 104, 194, 274, 281, 349, 351-352.

Related Primitives: baselineskip, lineskiplimit.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

lineskiplimit Paragraph
0pt * Parameter (dimen)
Synopsis: \lineskiplimit=<dimen>

Description:

    IF the glue specified by \baselineskip brings two adjacent boxes in a vertical list closer together than \lineskiplimit, then \lineskip glue is placed between the boxes [78].
Example:

     \parindent=1.5pc\hsize=4.75in
     \baselineskip=12pt
     \lineskip=0pt
     \lineskiplimit=0pt
     \tstory\par% The \adjdemerits reference page holds the definition of \tstory
     \baselineskip=9pt
     \lineskip=3pt
     \lineskiplimit=1pt
     \tstory\par
Produces: See typeset version.

Comments:

  • The first paragraph is set 10/12 (10 point type on 12 points of space). The distance between the first and last baseline in the paragraph is exactly 60 points.
  • The second paragraph is set 10/9. While the interline spacing of the two paragraphs appears to be quite similar, careful measurement shows the first and last baselines are about 63 points apart.
TeXbook References: 78-80. Also: 78-80, 104, 194, 274, 281, 349, 351-352, 362.

Related Primitives: baselineskip, lineskip.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

long Macro
Command
Synopsis: \long<macro-definition assignment>

Description:

    A macro is not allowed to have an argument which contains \par, unless the macro is declared \long [205]. A macro may also be declared \global or \outer. All three prefixes may be used in any order. Also, a prefix can occur more than once (e.g., `\long\global\long\gdef{. . .}') [206]. If two tokens compared by \ifx are macros, TeX includes each token's status with respect to \long in deciding if the two are the same or not [210].
Example:

  1. \long\def\tempabiod#1#2% {author}{text}
  2. {%
  3.   \bgroup
  4.      \selffamily AF
  5.      \parindent=1.5pc
  6.      {\bf\noindent AUTHOR BIOGRAPHICAL DATA:}\par
  7.      \def\temptyA{#1}%
  8.      \ifx\temptyA\empty
  9.      \else
 10.           {\bf\noindent #1 }%
 11.      \fi
 12.      #2\par
 13.   \egroup
 14. }
 15. \tempabiod{Fyodor Dostoyevsky}{was born in Moscow in 1821. At the age
 16. of twenty-seven he was arrested for promoting socialism and was
 17. sentenced to be executed. On the day of the execution the Tsar changed
 18. the sentence to a prison term in Siberia \char144
 19.
 20. After four years in Siberia and a mandetory term in the army he
 21. received a full pardon and was allowed to return to St. Petersburg.
 22. His many books include: \char144}
Produces: See typeset version.

Comments:

  • This shows a typical use of \long. Since the text for an author may run several paragraphs, the macro must be \long if the text is passed as a parameter.
  • However, the text doesn't have to be treated as a paramter. The macro \tempabiod could be broken into two pieces. The first would have the author as its singe parameter and would contain lines 1-11. The second would have no parameters and would hold: \par\egroup.
  • Line 15 would be changed to use the first macro, and `{was' would be changed to just `was'. Finally, the `}' on line 22 would be changed to the second macro.
  • The example on the \endgroup reference page is similar to this two-macro method.
TeXbook References: 205-206. Also: 205-206, 210, 275, 331, 375, 378, 382.

Related Primitives: def, edef, gdef, xdef, global, outer.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

looseness Paragraph
0 * Parameter (integer)
Synopsis: \looseness=<number>

Description:

    THE command `\looseness=l' tells TeX to try and make the current paragraph l lines longer (if l is > 0) or l lines shorter (if l < 0) while maintaining the general tolerances used to typeset the ms. IF l is > 0, a tie `~' is often placed between the last two words in the paragraph to prevent a short last line [103-104]. The parameter is reset to zero at the end of every paragraph or when internal vertical mode is started [349].
Example:

     \hsize=4.5in
     \tstory\par% The \adjdemerits reference page holds the definition of \tstory
     \vskip6pt
     {\looseness=-1
     \tstory\par}
Produces: See typeset version.

Comments:

  • The above paragraph does not work well with \looseness=1, but it does tighten.
  • This command is often used to fine-tune the pages in an article or book (e.g., to remove widow\mkindex{widow line} lines). It works best with longer paragraphs.
TeXbook References: 103-104. Also: 103-104, 109, 273, 342, 349.

Related Primitives: linepenalty.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

lower Kern
Command
Synopsis: \lower<dimen><box>

Description:

    THIS command lowers (or raises with a negative <dimen>) a box on the current list. It may only be used in horizontal mode [285] or math mode [290].
Example:

     \selffamily AA
     \hskip 1in
     \hbox{T\kern-.1667em\lower.5ex\hbox{E}\kern-.125em X}
Produces: See typeset version.

Comments:

  • This combines two kerns with \lower to make the TeX logo [66].
TeXbook References: 285. Also: 66, 80, 151, 179, 285, 290.

Related Primitives: raise, moveleft, moveright.

For Additional Examples, see: halign, mathchoice

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

lowercase Character
Command
Synopsis: \lowercase{<token list>}

Description:

    THIS command converts every character in the token list to its \lccode value unless that value is zero in which case no change is made. The conversion is made in TeX's stomach [41]. Expansion is suppressed during the conversion [215]. Active characters (category 13) behave like character tokens and may be converted [307].
TeXbook References: 41. Also: 41, 215, 279, 307, 345.

Related Primitives: lccode, uppercase.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

mag Job
1000 * Parameter (integer)
Synopsis: \mag=<number>

Description:

    TEX is able to process a document at different magnifications. However, if TeX is preparing dvi output, as it usually is, then a single magnification must be used for the whole document. The desired magnification is converted to a decimal, multiplied by 1000, and stored in the parameter \mag. For example, a 20% increase becomes 1.2 and then 1200; a 50% reduction becomes 0.5 and then 500. The number assigned to \mag should be between 1 and 32768 [60]. In order for \mag to work properly, all dimensions in the document need to be prefixed by ``true'' (e.g., \hsize=6.5true in). Otherwise, the material will be magnified, but part of it may spill off the edge of the page [59-60].
TeXbook References: 60. Also: 60, 270, 273, 348.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

mark Marks
Command
Synopsis: \mark{\}

Description:

    MOST reference works (e.g., a dictionary, encyclopedia, cummulative index, textbook, or this book) contain guide words at the top of each page. The words are supposed to help a user locate a particular page. TeX uses the \mark command to mark special words in a document. Then, when each page is placed in \box255, TeX sets up the following three quantities: a) |\firstmark| is the mark text that was first encountered on the page that was just boxed; b) |\botmark| is the mark text that was most recently encountered on the page that was just boxed; and c) |\topmark| has the value that |\botmark| had on the previous page. The quantities are null or empty at the start of a .ms. If a page contains no \mark's, each quantity is set to the \botmark on the previous page [258]. The following example is a variation of the one of page 258 in The TeXbook. A six page document contains ten marks, each of which holds a single letter A-J. Pages 1 and 5 have no marks; page 2 has A and B; page 3 has C, D, and E; page 4 has F; and page 6 has G, H, I, and J. Then
    On page | \topmark is | \firstmark is | \botmark is
1 | null | null | null
2 | null | A | B
3 | B | C | E
4 | E | F | F
5 | F | F | F
6 | F | G | J
    Works that use guide words either use the first and last marked items on each page, or they use the first item on verso pages and the last item on recto pages. There is general agreement on what the last item on a page should be. However, there is not agreement on what the first item is. Dictionaries generally say the first item is the first physical item on the page. An item continued from the previous page does not count. Text books and this book say the first item is the first logical item on the page. If the page begins with the continuation of an item, then that item is the first item. But, if the page begins with a totally new item, it is the first item. If this seems overly involved, the \mark's provided by TeX work with dictionaries, but not with text books unless the mark text is made to hold more than a single word or phrase. This is explained in detail on pages 259-260 of The TeXbook [259]. Marks can appear in horizontal or math lists, but they will not be used unless they migrate into the main vertical list [280].
TeXbook References: 258-259. Also: 95, 157, 216, 258-263, 280, 417, 454.

Related Primitives: botmark, firstmark, topmark, splitbotmark, splitfirstmark.

For Additional Examples, see: iffalse, iftrue

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

mathaccent Math (Character)
Command
Synopsis: \mathaccent<15-bit number><single character or {subformula}>

Description:

    THIS command gets the math character whose \mathchar is <15-bit number>; treats the character as an accent; and centers it over the following character or subformula [157]. TeX makes the resulting item a class 0 (ordinary) atom [170]. The command works best if the accent is applied to a single character. Even if the accent comes in several sizes (e.g., Plain TeX's \widehat or \widetilde), it may not be able to grow enough to cover all subformulas [136].
Example:

  1. \def\Widehat{\mathaccent"0362 }% the space before the } is important!
  2. \def\Hat{\mathaccent"705E }
  3. $\Widehat x$, $\Widehat {xy}$, $\Widehat {xyz}$, $\Widehat {wxyz}$,
  4. $\Widehat {x^2}$, $\Widehat {3x^2}$, $\Widehat {3x^2+4}$\par
  5. In a paragraph we say `\^x', but in math we say `$\Hat x$'.
Produces: See typeset version.

Comments:

  • Lines 1-2 are definitions made in Plain TeX.
  • Lines 3-4 show that \Widehat has a maximum width.
  • Line 5 is a reminder that different commands are used to get accents in paragraphs (horizontal mode) and in math expressions (math mode).
TeXbook References: 157, 291. Also: 135-136, 157, 170, 291, 359, 443.

Related Primitives: mathchar, skewchar, mathord.

For Additional Examples, see: skewchar

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

mathbin Math
Command
Synopsis: \mathbin<single character or {subformula}>

Description:

    THIS command makes the following math symbol or subformula have class 2, i.e., binary. TeX considers the class of a subformula when it puts space around the subformula and when it decides how to typeset surrounding subformulas [155].
Example:

     \tf{}0 % the mathord reference page defines \tf.
     \tf{\mathbin}1
     \hbox to \hsize{\box0\hfill\box1}
Produces: See typeset version.

Comments:

  • This example shows what happens if almost every symbol in an expression is treated as a \mathbin. It is similar to the second example on the \mathord reference page. That page gives the definition of \tf.
TeXbook References: 155, 291. Also: 155, 291, 361.

Related Primitives: mathord, mathop, mathrel, mathopen, mathclose, mathpunct, mathinner.

For Additional Examples, see: mathchoice, mathord

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

mathchar Math (Character)
Command
Synopsis: \mathchar<15-bit number>

Description:

    AFTER the necessary math fonts and font families are setup, \mathchar provides one way to assign mathcodes to control sequences and to refer to math symbols. The 15-bit number should be viewed as four hex digits. The first digit gives the symbol's class which is between 0 and 7; the second digit gives the symbol's family; and the last two digits give the symbol's position in the font whose family number is digit two [155].
Example:

  1. \font\ttf =pc2ki9y at 10pt \font\ttfb =pc2bi9y at 10pt %italics & bold italics.
  2. \font\tsf =pc2ki9y at  7pt \font\tsfb =pc2bi9y at  7pt
  3. \font\tssf=pc2ki9y at  5pt \font\tssfb=pc2bi9y at  5pt
  4. \textfont15=\ttf           \textfont14=\ttfb
  5. \scriptfont15=\tsf         \scriptfont14=\tsfb
  6. \scriptscriptfont15=\tssf  \scriptscriptfont14=\tssfb
  7. \def\test #1.{#1. $\Eth = x^2$, $\eth = 2x$\par}
  8. \def\testb #1.{#1. $\caslb\Etha = x^2$, $\caslb\etha = 2x$\par}
  9. \def\caslb{\fam14 }
 10. \def\Eth{\mathchar"0FB2}
 11. \def\eth{\mathchar"0FB3}
 12. \mathchardef\Etha="7FB2
 13. \mathchardef\etha="7FB3
 14. \test 1.
 15. \testb 2.
Produces: See typeset version.

Comments:

  • This example is similar to the one on the \mathcode reference page. The difference is: that page uses \mathcode to convert Ð and ð into math characters, and this page uses \mathchar and \mathchardef.
  • Lines 1-3 create six control symbols for Caslon fonts in appropriate sizes.
  • Lines 4-6 make family 15 a Caslon italics family and family 14 a Caslon bold italics family.
  • Lines 7 and 8 define two simple macros which are used to test things, and line 9 defines a macro used on line 8.
  • Lines 10-13 define four new control sequences for the new math characters. Each character is defined twice, once using \mathchar and once using \mathchardef.
  • Finally, lines 14-15 run two tests which show the new characters work. Plain TeX defines over 150 math symbols using \mathchardef and fewer than 10 using \mathchar.
TeXbook References: 155. Also: 155, 289.

Related Primitives: mathcode, mathchardef, fam.

For Additional Examples, see: skewchar

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

mathchardef Math (Character)
Derived Command
Synopsis: \mathchardef<control sequence>=<15-bit number>

Description:

    THE command `\mathchardef\cs=<15-bit number>' is an efficient alternate to `\def \cs{\mathchar<15-bit number>}' [155]. Control sequences defined by \mathchardef may be used with `\the'. That combination returns <number> in decimal notation [214]. Expansion is suppressed when TeX is reading the <control sequence> [215]. TeX uses hexadecimal notation when it expands `\meaning<control sequence>' [336].
Example:

  1. \mathcode`\'= "8000 % Force ' (right quote) to be active in math mode.
  2. {\catcode`\'=\active \gdef'{^\bgroup\primeA}}% Global change to Plain Tex.
  3. \def\primeA{\prime\futurelet\next\primeB}
  4. \mathchardef\prime="0230 % Page 431 of The TeXBook shows a prime in position
  5. \def\primeB%               "30 of font 2.
  6. {%
  7.      \ifx'\next
  8.           \let\nxt=\primeC
  9.      \else
 10.           \ifx^\next
 11.                \let\nxt=\primeD
 12.           \else
 13.                \let\nxt=\egroup
 14.           \fi
 15.      \fi
 16.      \nxt
 17. }
 18. \def\primeC#1{\primeA}
 19. \def\primeD#1#2{#2\egroup}
 20. If $f(x) = 2x^3-4x^2+5x-6$, $f'(x)=6x^2-8x+5$, $f''(x)=12x-8$, $f'''(x)=12$,
 21.  and $f''''(x) = f^{(4)}(x) = 0$.\par
 22. Also, $x'\cdot x' = x'^2$. But what is $x'^{y^2}$?\par
 23. Compare f'(x) with $f'(x)$.
 24. {\catcode`\'=\active \gdef'{^\bgroup\prim@s}}%reset Plain TeX value.
Produces: See typeset version.

Comments:

  • This example illustrates: \mathchardef, mathcode, and \futurelet. It is an adaptation of material in The TeXbook [357].
  • The example explains how TeX makes f'(x) look one way in horizontal mode and another way in math mode (e.g., see the output from line 23).
  • Line 1 sets the mathcode of the right quote to "8000. It is the special value that makes math characters active.
  • Line 2 says, ``Make the right quote active and globally define it to be `^\bgroup \primeA'.'' Note the braces around the line. They allow the definition to be made, but prevent the right quote from always being active.
  • Line 3 defines \primeA. It makes a \prime which is defined on the next line. The \futurelet sets \next equal to the character following the original right quote and then performs \primeB.
  • The definition of \prime on line 4 uses \mathchardef and is font dependent. The comment at the end of the line shows where CM has the prime symbol and should explain the value used earlier on the line.
  • Lines 7-8 allow several right quotes to build up. The examples produced by lines 20-21 show this.
  • Lines 10-11 are designed to cover the case shown on line 22. In the expression x'^2 on line 22, the arguments of \primeD are `^' and `2'. Also, the expression produces six tokens: x ^ \bgroup \prime 2 \egroup. In the expression x'^{y^2} later on the line, the arguments of \primeD are: `^' and `y^2'. That expression also produces six tokens: x ^ \bgroup \prime y^2 \egroup.
  • Finally, consider line 23. The first right quote appears in horizontal mode which uses catcodes. Since catcode`\'=12 (other), TeX does not see the definition made on line 2, and so it typesets a right quote. But the second right quote on line 23 appears in math mode which uses mathcodes. Recall line 1: `\mathcode`\'= "8000'. That value tells TeX that the right quote is now active. So, TeX uses the definition on line 2, and things follow as described above.
TeXbook References: 155. Also: 155, 199, 214, 215, 271, 277, 289, 336, 358, 394.

Related Primitives: mathchar.

For Additional Examples, see: displaylimits

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

mathchoice Math
Command
Synopsis: \mathchoice{<math>}{<math>}{<math>}{<math>}

Description:

    MANY formatting packages used with TeX provides access to special math symbols. However, there are times when a symbol is required which is not readily available. The \mathchoice command is used to construct new symbols. Specific rules for constructing the symbol must be given for each of the four main styles. Then the symbol may be used in any expression, and it should blend in with the rest of the expression [151].
Example:

  1. \def\tsym#1#2#3% point size 1; point size 2; amount to lower symbol
  2. {%                                           units are the x-height: ex
  3.      \hbox
  4.      {%
  5.           \lower#3ex\hbox
  6.           {%
  7.                \maketfont A1{#1}% Choose Caslon, roman using point size 1.
  8.                \char140 %         See below for \char140 and \char141
  9.                \kern-0.2em
 10.                \raise0.12ex
 11.                \hbox{\maketfont A1{#2}+}%
 12.                \kern-0.2em
 13.                \char141 %
 14.           }%
 15.      }%
 16. }
 17. \def\tcA{\mathbin{\tsym {14}{10}{0.15}}}% This won't scale!
 18. \def\tc{\mathchoice
 19.      {\mathbin{\tsym {14}{10}{0.15}}}{\mathbin{\tsym {12}{10}{0.15}}}
 20.      {\mathbin{\tsym {08}{06}{0.06}}}{\mathbin{\tsym {06}{05}{0.06}}}}
 21. The symbol `$\tcA$' is built from three characters: `\char140 +\char141'.
 22. \halign{\qquad#\hfil&\quad$\displaystyle{x {#} y}$\hfil&
 23.   \quad$\textstyle{x# y}$\hfil&
 24.   \quad$\scriptstyle{x# y}$\hfil&
 25.   \quad$\scriptscriptstyle{x# y}$\hfil\cr
 26.   &\omit\quad\bf display&\omit\quad\bf text&\omit\quad\bf script&
 27.                          \omit\quad\bf scriptscript\cr
 28.   |\tc|: &\tc  &\tc  &\tc  &\tc \cr
 29.   |\tcA|:&\tcA &\tcA &\tcA &\tcA\cr}
 30. $$\underbrace{\hbox{$x\tc  y$,\quad}
 31.   \hbox{$z^{x\tc  y}$, and\quad}
 32.   w \tc  z^{{x\tc  y}^{x\tc  y}}}_{|\tc|}
 33.   \hbox{\quad vs \quad}
 34.   \underbrace{\hbox{$x\tcA y$,\quad}
 35.   \hbox{$z^{x\tcA y}$, and\quad}
 36.   w \tcA z^{{x\tcA y}^{x\tcA y}}}_{|\tcA|}$$
Produces: See typeset version.

Comments:

  • This example builds two forms of a new binary symbol: \tcA and \tc.
  • Each form uses the macro \tsym shown on lines 1-16. That macro is straightforward except for the reference to \maketfont on lines 7 and 11. It requires three parameters. The first two select a PostScript font family and face (e.g., Caslon 224 and roman). The third specifies the desired point size. The macro builds an appropriate \font statement and makes the new font the current one.
  • Line 17 builds the version of the new symbol which is the same size in all styles.
  • Lines 18-20 use \mathchoice to build a scalable symbol. This requires a description of the new symbol in each of the four major styles: desplay, text, script, scriptscript. Each style requires \mathbin (since the new symbol is binary) and \tsym (with values appropriate for the style). I used trial and error to find the values used here.
  • Lines 21-36 serve as a test. In particular, line 21 typesets the characters used on lines 8 and 13.
  • Lines 22-29 build a table which uses both forms of the new symbol in each of the major styles.
  • Lines 30-36 mix in-line and display math expressions using both forms of the new symbol. Lines 30 and 34 use \underbrace which is provided by \Plain TeX.
TeXbook References: 151. Also: 151, 157, 292.

Related Primitives: mathbin, mathclose, mathop, mathopen, mathord, mathpunct, mathrel, displaystyle, textstyle, scriptstyle, scriptscriptstyle.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

mathclose Math
Command
Synopsis: \mathclose<single character or {subformula}>

Description:

    THIS command makes the following math symbol or subformula have class 5, i.e., closing. TeX considers the class of a subformula when it puts space around the subformula and when it decides how to typeset surrounding subformulas [155].
Example:

     \tf{}0 % see the \mathord reference page for the definition of \tf.
     \tf{\mathclose}1
     \hbox to \hsize{\box0\hfill\box1}
Produces: See typeset version.

Comments:

  • This example shows what happens if almost every symbol in an expression is treated as a \mathclose. It is similar to the second example on the \mathord reference page. That page gives the definition of \tf.
TeXbook References: 155, 291. Also: 155, 291, 322, 359.

Related Primitives: mathord, mathop, mathbin, mathrel, mathopen, mathpunct, mathinner.

For Additional Examples, see: mathord

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

mathcode Math (Character)
Internal Quantity
Synopsis: \mathcode<8-bit number>=<15-bit number>

Description:

    IN math mode TeX typsets math symbols which are identified by mathcodes having four hex digits. The first digit in a mathcode is the class number. It must be between 0 and 8. If it is 8, the remaining three digits must be 0. Otherwise, the remaining three digits may have any hex value. The second digit is the family number. It specifies a math font. The final two digits specify a character in the math font for the family number. The following table summarizes mathcode values less than 8000 and class numbers less than 8 [154].
    Mathcode Values:"wxyz |  |  | NULL | Class Numbers
Digit | Values | Usage | - | Class | Meaning | Class | Meaning
w | 0-7 | Class number | - | 0 | Ordinary | 4 | Opening
x | 0-"F | Family number | - | 1 | Large operator | 5 | Closing
yz | 0-"FF | Character code | - | 2 | Binary operation | 6 | Punctuation
- |  |  | - | 3 | Relation | 7 | Variable family
    There are two types of math symbols: simple characters (i.e., letters, digits, `.', `+', `]', and other items with a \char value) and control sequences. The \mathcode command assigns a mathcode to a simple character. The version of INITEX used with Plain TeX assigns a simple character whose \char value is x the following \mathcode: 7000 + x if x is a digit; 7100 + x if x is an uppercase or lowercase letter; x in all other cases. For example, the mathcodes assigned by INITEX to `0', `A', and `+' are 7030, 7141, and 002B [155]. Plain TeX makes the redefinition: `\mathcode`\+= 202B'. It tells TeX that `+' is a binary operation [344]. The \mathchar and \mathchardef commands assign a mathcode to a control sequence. If a math symbol has mathcode 8000, TeX treats the symbol in math mode as if it had catcode 13 (active) [155].
Example:

  1. The new math chars are: {\it \char"B2, \char"B3}, {\bi ^^b2, and ^^b3}.\par
  2. The mathcodes are: ^^b2=\the\mathcode"B2, ^^b3=\the\mathcode"B3.% 178 = "B2.
  3. The mathcodes are: $^^b2=\the\mathcode"B2$, $^^b3=\the\mathcode"B3.$\par
  4. \font\ttf =pc2ki9y at 10pt \font\ttfb =pc2bi9y at 10pt %italics & bold italics.
  5. \font\tsf =pc2ki9y at  7pt \font\tsfb =pc2bi9y at  7pt
  6. \font\tssf=pc2ki9y at  5pt \font\tssfb=pc2bi9y at  5pt
  7. \textfont15=\ttf           \textfont14=\ttfb
  8. \scriptfont15=\tsf         \scriptfont14=\tsfb
  9. \scriptscriptfont15=\tssf  \scriptscriptfont14=\tssfb
 10. \def\test #1.{#1. $\char"B2 = x^2$, $^^b3 = 2x$\par}%               italics
 11. \def\testb #1.{#1. $\caslb ^^b2 = x^2$, $\caslb\char"B3 = 2x$\par}% bold italics
 12. \test 1.
 13. \mathcode"B2="0FB2 \test 2.
 14. \mathcode"B3="0FB3 \test 3.
 15. \def\caslb{\fam14 }\testb 4.
 16. \mathcode"B2="7FB2 \testb 5.
 17. \mathcode"B3="7FB3 \testb 6.\test 7.% First test bold italics, then italics.
Produces: See typeset version.

Comments:

  • This example shows how to make italics and bold italics versions of two new math characters: Ð and ð. Each is in Caslon 224, but neither has a CM form. Neither character is a standard ASCII character, and this example uses two methods to reference the characters: \char"XY and ^^xy [44-45].
  • Line 1 shows what is desired. It typesets the four characters using horizontal mode.
  • Lines 2 and 3 typeset the current mathcodes of the two characters twice: once in horizontal mode and once in math mode. The results suggest it will require some work to convert Caslon's special characters into math symbols.
  • Lines 4-6 create six control symbols for Caslon fonts in appropriate math sizes.
  • Lines 7-9 make family 15 a Caslon italics family and family 14 a Caslon bold italics family.
  • Lines 10 and 11 define two simple macros which are used to test things, and lines 12-17 run six tests.
  • The first test fails to typeset either character as a math character. Clearly, the setup performed in lines 4-9 is not sufficient to make math characters work. The current mathcodes have class and family 0, and CM does not have characters in the positions listed by line 2 [427].
  • Line 13 assigns Ð a mathcode with class 0 (ordinary), family F, and character B2 which is decimal 178. Test 2 works with Ð as a math character, and line 14 makes a similar assignment for ð. Test 3 shows both new characters work in italics.
  • Line 15 defines a control sequence which switches to family 14. Then it runs a slightly different test which uses the new control sequence. Neither character is picked up and typeset in bold.
  • Lines 16-17 change the class of each mathcode from 0 to 7. Once each character's code is changed, bold italics works, and test 7 shows plain italics continues to work. The \fam reference page explains why the switch from class 0 to class 7 works as this example shows it does.
TeXbook References: 154-155. Also: 134, 154-155, 214, 271, 289, 319, 326, 344.

Related Primitives: mathchar, delcode, delimiter, fam, char.

For Additional Examples, see: fam, mathchardef

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

mathinner Math
Command
Synopsis: \mathinner<single character or {subformula}>

Description:

    THIS command is similar to \mathord and the other commands used to specify math parts of speech, except \mathinner does not have a class number. TeX treats certain subformulas such as fractions and `\left ... \right' constructions as inner, and it adds extra space on each side of the subformula in certain circumstances. The \mathinner command tells TeX to treat the following character or subformula as inner [155 and 170].
Example:

  1. \mathchardef\ldotpA="613A
  2. \def\ldotsA{\mathinner{\ldotpA\ldotpA\ldotpA}}
  3. \def\ldotsB{\ldotpA\ldotpA\ldotpA}\par
  4. $|x\ldotsA y|$ vs $|x\ldotsB y|$ vs $|x\R2\ldotsB\R2 y|$
  5. $$2\int_0^1 3x^2 dx = 2\left[x^3\right]_0^1 = 2.\hskip0.25in
  6.   2\int_0^1 3x^2 dx = 2\Bigl[x^3\Bigr]_0^1  =2. \hskip0.25in
  7.   2\int_0^1 3x^2 dx = 2\mathinner{\Bigl[x^3\Bigr]_0^1} = 2.$$
Produces: See typeset version.

Comments:

  • Line 2 is the Plain TeX definition of \ldots [359], and lines 3-4 show what happens if the \mathinner on line 2 is removed. The first and third formulas are about 2 points wider than the middle one. So, the \R2 adds space similar to what \mathinner adds automatically.
  • Lines 5-7 evaluate a definite integral. Line 5 makes left and right brackets that are too small. Line 6 fixes that, but the `2' before the `[' is now closer that is was on line 5. Line 7 uses \mathinner to restore the spacing made by line 5.
TeXbook References: 158, 170, 291. Also: 155, 170-171, 199, 291, 359.

Related Primitives: mathord, mathop, mathbin, mathrel, mathopen, mathclose, mathpunct.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

mathop Math
Command
Synopsis: \mathop<single character or {subformula}>

Description:

    THIS command makes the following math symbol or subformula have class 1, i.e., large operator. TeX considers the class of a subformula when it puts space around the subformula and when it decides how to typeset surrounding subformulas [155].
Example:

     \tf{}0 % see the \mathord reference page for the definition of \tf.
     \tf{\mathop}1
     \hbox to \hsize{\box0\hfill\box1}
Produces: See typeset version.

Comments:

  • This example shows what happens if almost every symbol in an expression is treated as a \mathop. It is similar to the second example on the \mathord reference page. That page gives the definition of \tf.
TeXbook References: 155, 291. Also: 155, 178, 291, 324-325, 361.

Related Primitives: mathord, mathbin, mathrel, mathopen, mathclose, mathpunct, mathinner.

For Additional Examples, see: mathord

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

mathopen Math
Command
Synopsis: \mathopen<single character or {subformula}>

Description:

    THIS command makes the following math symbol or subformula have class 4, i.e., opening. TeX considers the class of a subformula when it puts space around the subformula and when it decides how to typeset surrounding subformulas [155].
Example:

     \tf{}0 % see the \mathord reference page for the definition of \tf.
     \tf{\mathopen}1
     \hbox to \hsize{\box0\hfill\box1}
Produces: See typeset version.

Comments:

  • This example shows what happens if almost every symbol in an expression is treated as a \mathopen. It is similar to the second example on the \mathord reference page. That page gives the definition of \tf.
TeXbook References: 155, 291. Also: 155, 291, 322, 359.

Related Primitives: mathord, mathop, mathbin, mathrel, mathclose, mathpunct, mathinner.

For Additional Examples, see: mathord

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

mathord Math
Command
Synopsis: \mathord<single character or {subformula}>

Description:

    THIS command makes the following math symbol or subformula have class 0, i.e., ordinary. TeX considers the class of a subformula when it puts space around the subformula and when it decides how to typeset surrounding subformulas [155].
Example:

  1. \def\p#1{\tp{#1}{\Eth}}% see the \mathchar   reference page for \Eth.
  2. \def\P#1{\tp{#1}{\tcA}}% see the \mathchoice reference page for \tcA.
  3. \def\tp#1#2%
  4. {%
  5.      $x
  6.      \ifcase#1
  7.         \mathord % class 0
  8.      \or\mathop %        1
  9.      \or\mathbin %       2
 10.      \or\mathrel %       3
 11.      \or\mathopen %      4
 12.      \or\mathclose %     5
 13.      \or\mathpunct %     6
 14.      \fi
 15.      #2
 16.      y$
 17. }
 18. \halign{\quad#&&\quad\hfil#\hfil\cr
 19. &\multispan7\bf\hfil Spacing and Classes in Math Expressions\hfil\cr
 20. &\multispan7\quad\leaders\hrule height 7pt depth-6.6pt\hfill\cr
 21. \noalign{\kern-7pt}
 22. &\it Ordinary&\it Operator&\it Binary&\it Relation&\it Opening&\it Closing&
 23.  \it Punctuation\cr
 24. &\p0&\p1&\p2&\p3&\p4&\p5&\p6\cr
 25. &\P0&\P1&\P2&\P3&\P4&\P5&\P6\cr}
 26. \def\tf#1#2%
 27. {%
 28.      \setbox#2=\vbox{\hsize=2.4in
 29.      $$#1f#1(#1x#1)#1=#1\sum_{#1{#1i#1=#1 0}}^{#1\infty}#1a_{#1i}#1x^{#1i}
 30.      \hbox{,\ where\ }#1a_{#1i}#1={#1{#1f#1{^{#1{#1(#1i#1)}}#1(#10#1)}}
 31.      \over{#1{#1i#1!}}}.$$}
 32. }
 33. % f(x)=\sum_{i=0}^\infty a_ix^i\hbox{,\ where\ }a_i={f^{(i)}(0)\over i!}
 34. \tf{}0
 35. \tf{\mathord}1
 36. \hbox to \hsize{\box0\hfill\box1}
Produces: See typeset version.

Comments:

  • This example has two parts: a table which shows the relationship between the spacing in an expression and the class of symbols in the expression, and two expressions which show what happens if each symbol in an expression has its class changed.
  • Lines 18-25 typeset the table. It uses the macros \p and \P, each of which requires a single parameter. Lines 1-2 show those macros are a front-end to \tp defined on lines 3-17. Although \tp is long, it is quite simple. It builds: a math list containing `x'; one of the math class commands (determined by parameter 1 on lines 24-25); a math symbol; and `y'. The math symbol is either \Eth which is defined on the \mathchar reference page or \tcA which is defined on the \mathchoice reference page.
  • Lines 26-36 typeset the two expressions. Most of the work is done by the \tf macro which is called on lines 34-35. The second parameter in \tf is the box number used on line 28, and the first parameter is either empty or \mathord. Lines 29-31 use the first parameter and are almost unreadable. They began as line 33. In fact the call made on line 34 is the same as line 33. Also, the call made on line 35 is the same as putting \mathord before nearly every symbol on line 33.
TeXbook References: 155, 291. Also: 88-89, 155, 291.

Related Primitives: mathop, mathbin, mathrel, mathopen, mathclose, mathpunct, mathinner.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

mathpunct Math
Command
Synopsis: \mathpunct<single character or {subformula}>

Description:

    THIS command makes the following math symbol or subformula have class 6, i.e., punctuation. TeX considers the class of a subformula when it puts space around the subformula and when it decides how to typeset surrounding subformulas [155].
Example:

     \tf{}0 % see the \mathord reference page for the definition of \tf.
     \tf{\mathpunct}1
     \hbox to \hsize{\box0\hfill\box1}
Produces: See typeset version.

Comments:

  • This example shows what happens if almost every symbol in an expression is treated as a \mathpunct. It is similar to the second example on the \mathord reference page. That page gives the definition of \tf.
TeXbook References: 155, 291. Also: 155, 291.

Related Primitives: mathord, mathop, mathbin, mathrel, mathopen, mathclose, mathinner.

For Additional Examples, see: mathord

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

mathrel Math
Command
Synopsis: \mathrel<single character or {subformula}>

Description:

    THIS command makes the following math symbol or subformula have class 3, i.e., relation. TeX considers the class of a subformula when it puts space around the subformula and when it decides how to typeset surrounding subformulas [155].
Example:

     \tf{}0 % see the \mathord reference page for the definition of \tf.
     \tf{\mathrel}1
     \hbox to \hsize{\box0\hfill\box1}
Produces: See typeset version.

Comments:

  • This example shows what happens if almost every symbol in an expression is treated as a \mathrel. It is similar to the second example on the \mathord reference page. That page gives the definition of \tf.
TeXbook References: 155, 291. Also: 155, 291, 359-361.

Related Primitives: mathord, mathop, mathbin, mathopen, mathclose, mathpunct, mathinner.

For Additional Examples, see: mathord

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

mathsurround Math (Kern)
0pt * Parameter (dimen)
Synopsis: \mathsurround<glue>

Description:

    THIS parameter holds glue which TeX inserts when it begins and ends non-display math mode. The glue disappears if it appears at the beginning or end of a line. TeX uses the value in force when it reads the `$' which ends math mode [162].
Example:

  1. \def\tfn
  2. {%
  3.      If $h$ is odd, $h \vert u_d$. If h is even, then $u_m$ and $u_n$
  4.       are even so $u_{rm}$, $u_{sn}$, $v_{rm}$, $v_{sn}$ are all even
  5.       by (ii) and (iii).
  6.      $\the\mathsurround$ vs $ \the\mathsurround$ vs \the\mathsurround.
  7. }
  8. \everymath{\mathsurround=1pt}\tfn\vskip0.5\baselineskip
  9. \everymath{\mathsurround=0.5pt}\tfn\vskip0.5\baselineskip
 10. \everymath{}\tfn
Produces: See typeset version.

Comments:

  • This example has two parts.
  • First, lines 8-10 use the macro \tfn defined on lines 1-7 to typeset a sentence mixing text and in-line mathematics. The material is typeset using three different values for \mathsurround.
  • Second, line 6 adds some material to the end of each sentence. Namely, it tries to typeset the current value of \mathsurround. It tries three times: twice in math mode (with different results) and once in horizontal mode. It is not surprising that the results in math and horizontal modes are different. But it is surprising, at least to the author, that a space is required after the first `$' to get the correct value in math mode.
TeXbook References: 162. Also: 97, 162, 274, 305, 314, 323, 353, 447.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

maxdeadcycles Job
25 * Parameter (integer)
Synopsis: \maxdeadcycles=<number>

Description:

    EACH time TeX prepares to perform the output routine, it checks if \deadcycles is less than \maxdeadcycles. If it is, TeX increases \deadcycles by 1 and performs the output routine. If it is not, TeX issues an error message and performs the default output routine `\shipout\box255' [254-255].
TeXbook References: 255. Also: 255, 273, 348.

Related Primitives: deadcycles.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

maxdepth Page
4pt * Parameter (dimen)
Synopsis: \maxdepth=<dimen>

Description:

    EACH time TeX adds a box to the main page, it compares the depth of the box to \maxdepth. If the depth is larger than \maxdepth, TeX moves the reference point in the box down thereby increasing the height and decreasing the depth of the box [113]. The value of \maxdepth is stored when the first box or insertion is put on a new page. Changes to \maxdepth are not reflected until a new page is started [114].
TeXbook References: 113-114. Also: 112-114, 123-125, 255, 262-263, 274, 348, 400, 415.

Related Primitives: vsize, splitmaxdepth, boxmaxdepth, pagedepth.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

meaning Debugging
Command
Synopsis: \meaning<token>

Description:

    THIS command adds characters to the output stream which describe <token> [213]. Each character is assigned category code 12 (other) except for spaces which are assigned category code 10 (space) [214]. Expansion of tokens is suppressed [215]. If \cs is defined using \chardef or \mathchardef, TeX uses hexadecimal notation when it expands \meaning\cs [336].
Example:

  1. \chardef\abstract=92 % Note, 92 = "5C.
  2. `\abstract'---\meaning\abstract\par
  3. \def\bads#1
  4. {
  5.      Bad
  6.      #1
  7.      spaces
  8. }%Note, \bads is missing 5 %s.
  9. \def\goods#1%
 10. {%
 11.      Good%
 12.      #1%
 13.      spaces%
 14. }
 15. \meaning\bads---\par
 16. \meaning\goods---\par
 17. ---\goods{! No bad }.\par
 18. ---\bads{! Too many }. \par
 19. 1. \bads{! Too many }. Goodness. Gracious!\par
 20. 2. \bads{\it ! Too many }.Goodness. Gracious!\par
 21. \def\badS#1 { Bad #1 spaces }
 22. \meaning\badS---\par
 23. \meaning\bads---\par
 24. 3. \badS{\it ! Too many }.Goodness. Gracious!\par
Produces: See typeset version.

Comments:

  • Line 1 defines a control sequence for a `\', and line 2 typesets the new control sequence and its meaning.
  • Lines 3-8 define a simple macro which is missing five `%' symbols. Each may result in a spurious\mkindex{space`5`spurious} space which is often difficult to track down.
  • Lines 9-14 define a similar macro with the missing %'s.
  • Lines 15-16 typeset the meaning of the two macros. A close look shows four extra spaces in the replacement text for \bads and one space to the left of the `->'.
  • Lines 17-18 use each macro with an appropriate parameter to typeset a simple sentence. The results for line 18 bear close scrutiny. The sentence has the expected extra spaces, but it also has the period at the end of line 18 in the wrong place. What's going on?
  • Lines 19-24 and the fifth space (the one to the left of the `->' typeset by line 15) explain the mystery. TeX views \bads as identical to \badS which is defined on line 21. In particular, it treats the new line character at the end of line 3 as a space. So, when it is processing parameter one (on lines 18-20 and 24), it continues processing beyond the `}' (which normally ends the parameter) until it encounters a space.
TeXbook References: 213. Also: 213-215, 336, 382.

Related Primitives: show.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

medmuskip Math (Glue)
4mu plus 2mu minus 4mu * Parameter (muglue)
Synopsis: \medmuskip<muglue>

Description:

    THIS parameter holds the math glue used by medium spaces [168]. TeX automatically inserts thin, medium, and thick spaces in math formulas [167]. For example, it puts a medium space between ordinary and binary atoms in display and text styles [170]. Each type of space is a form of math glue and is expressed using mu units. There are 18mu in an em where the em is from family 2 (the math symbols font). The size of a mu depends on the current style since each style normally has a different size and hense a different em value. Math glue can stretch and shrink, and the Plain TeX value for \medmuskip has a small amount of stretch but can shrink to zero [168].
Example:

     \def\tf#1#2#3#4%
     {%
          \thinmuskip=#1
          \medmuskip=#2
          \thickmuskip=#3
          $$F_n = F_{n-1} + F_{n-2} \hbox{, for } n \ge 2.\eqno(#4.)$$
     }
     The Fibonacci numbers are defined by: $F_0=1$, $F_1=1$, and
     \tf{3mu}{4mu plus 2mu minus 4mu}{5mu plus 5mu}1
     \tf{3mu}{0mu}{5mu plus 5mu}2
     \tf{0mu}{0mu}{0mu}3
Produces: See typeset version.

Comments:

  • This example typesets the recursive definition of the Fibonacci numbers three times: the first uses Plain TeX values for the three spaces; the second makes the medium space zero; and the third makes all spaces zero.
TeXbook References: 168, 170. Also: 167-168, 170, 274, 349, 446.

Related Primitives: mskip, thinmuskip, thickmuskip.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

message Debugging
Command
Synopsis: \message<general text>

Description:

    THIS command writes an expanded token list on the terminal and to the log file [217]. The results of several messages may appear on the same line. If \newlinechar is assigned a value, that character may be used to begin a new line [228].
Example:

  1. \newlinechar=`@     % makes \message{} start on new line.
  2. \setbox0=\hbox{A}
  3. \message{@Hello There}
  4. \message{The height of box0 = \the\ht0.@}
  5. \message{The depth of box0 = \the\dp0.@ Byebye.}
  6. \message{Some message don't}
  7. \message{start on a new line.}
Produces: See typeset version.

Comments:

  • Lines 3-7 write several messages to the log file. Normally, TeX writes messages on the same line in the file. The assignment made on line 1 makes TeX begin a new line in the file each time it encounters a `@' in a message.
TeXbook References: 217. Also: 216, 217-218, 227-228, 279, 308, 328, 343-344, 355, 418.

Related Primitives: newlinechar.

For Additional Examples, see: pagedepth

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

mkern Math (Kern)
Command
Synopsis: \mkern<mudimen>

Description:

    THIS command inserts a kern with the specified math dimension into the current math list. It may only be used in math mode. Math dimensions must be given using mu units not pt or one of the other non-math units. There are 18 mu in an em where the em is from family 2 (the math symbols font). In particular, the size of a mu depends on the current style since each style normally has a different size and hense a different em value [168].
Example:

  1. \def\R#1{\mkern#1mu\relax}
  2. \def\L#1{\mkern-#1mu\relax}
  3. \def\strutA#1#2{\vrule height#1 depth#2 width0pt}
  4. \def\tsq#1%
  5. {%
  6.      $\sqrt 2\R#1 x$
  7.      \ifnum#1 < 9
  8.           vs~%
  9.      \fi
 10. }
 11. \def\tint#1%
 12. {%
 13.      $\int_0^x\L#1\int_0^y dF(x,y)$
 14.      \ifnum#1 < 9
 15.           vs
 16.      \fi
 17. }
 18. \tsq0\tsq1\tsq2\tsq3\tsq4\tsq5\tsq6\tsq7\tsq8\tsq9\par
 19. \strutA{12pt}{4pt}\tint0\tint1\tint2\tint3\tint4\tint5\tint6\tint7
 20. \tint8\tint9\strutA{12pt}{4pt}\par
Produces: See typeset version.

Comments:

  • The definition of \L on line 2 is a simplification of a macro given on the \ifmmode reference page.
  • The macros \tsq and \tint use \R and \L to add and remove space in increments of one mu.
  • The example on line 18 typesets the same expression ten times. It shows the spacing TeX gives and how things look if an additional mu is added before the x.
  • The example on lines 19-20 is similar, only each repetion of the expression removes one mu between the integral signs.
TeXbook References: 168. Also: 168, 280, 442.

Related Primitives: mskip, kern.

For Additional Examples, see: ifmmode

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

month Job
Parameter (integer)
Synopsis: \month

Description:

    AT the beginning of each job TeX sets this parameter to the current month (1-12) in the year [349].
Example:

  1. \def\mydate
  2. {%
  3.      \number\day \ %
  4.      \ifcase\month
  5.           \or Jan\or Feb\or Mar%
  6.           \or Apr\or May\or June%
  7.           \or July\or Aug\or Sep%
  8.           \or Oct\or Nov\or Dec%
  9.      \fi
 10.      \ \number\year
 11. }
 12. \mydate
Produces: See typeset version.

Comments:

  • Without the `%' on lines 5-8, an extra space creaps in for four months of the year.
TeXbook References: 349. Also: 273, 349, 406.

Related Primitives: day, year, time.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

moveleft Kern
Command
Synopsis: \moveleft<dimen><box>

Description:

    THIS command shifts a box left (or right if <dimen> is negative). It requires vertical mode [80].
Example:

     \hbox{This is a line of type.}
     \moveleft0.5in\vbox{This is a line of type shifted left.}
     \moveleft-0.5in\hbox{This is a line of type shifted right.}
Produces: See typeset version.

Comments:

  • This example shows \moveleft works with both hboxes and vboxes and can move a box left or right.
TeXbook References: 80-81. Also: 80-81, 282, 287.

Related Primitives: moveright, lower, raise.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

moveright Kern
Command
Synopsis: \moveright<dimen><box>

Description:

    THIS command shifts a box right (or left if <dimen> is negative). It requires vertical mode [80].
Example:

     \vbox{This is a line of type.}
     \moveright0.5in\hbox{This is a line of type shifted right.}
     \moveright-0.5in\vbox{This is a line of type shifted left.}
Produces: See typeset version.

Comments:

  • This example shows \moveright works with both hboxes and vboxes and can move a box right or left.
TeXbook References: 80-81. Also: 80-81, 221, 282.

Related Primitives: moveleft, lower, raise.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

mskip Math (Glue)
Command
Synopsis: \mskip<muglue>

Description:

    THIS command inserts special glue into a math exprssion. It may only be used in math mode. The glue is like ordinary glue except it uses `mu' units instead of `pt' or one of the other non-math units. There are 18 mu in an em where the em is from family 2 (the math symbols font). In particular, the size of a mu depends on the current style since each style normally has a different size and hense a different em value [168].
Example:

     \def\,{\mskip\thinmuskip}% These definitions use the Plain TeX values.
     \def\>{\mskip\medmuskip}
     \def\;{\mskip\thickmuskip}
     \def\!{\mskip-\thinmuskip}
     $\sqrt 2x$ vs $\sqrt 2\,x$ vs  vs $\sqrt 2\>x$ vs $\sqrt 2\;x$ vs $\sqrt 2\!x$
Produces: See typeset version.

Comments:

  • This example uses Plain TeX macros to change the spacing of an expression.
TeXbook References: 168. Also: 168, 290, 442.

Related Primitives: mkern, thinmuskip, medmuskip, thickmuskip, hskip, vskip.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

multiply Registers
Command
Synopsis: \multiply<numeric variable> by <number>

Description:

    THIS command multiplies the <numeric variable> by <number> (i.e., by an integer). The number must not produce a result which is too large for the variable otherwise TeX will generate an arithemetic overflow run-time error [118]. A <numeric variable> is: a) a parameter of type: integer, dimen, glue, or muglue; b) a token specified by \countdef, \dimendef, \skipdef, or \muskipdef; or c) a \count, \dimen, \skip, or \muskip register. The by is optional [276].
Example:

  1. \def\fixdimens#1#2% Want to compute: #1*#2/1000 and (#1*#2/1000)*1.2
  2. {%
  3. %  \bgroup
  4.      \dimen1=#1pt
  5.      \count2=#2
  6.      \count1=\dimen1
  7.      \multiply\count1 by \count2
  8.      \divide\count1 by 1000
  9.      \dimen1=\count1 sp
 10.      \count1=\dimen1
 11.      \multiply\count1 by 12% This is a hard way to multiply by 1.2
 12.      \divide \count1 by 10 % See the divide reference page for a better way
 13.      \dimen2=\count1 sp
 14.      Original point size = #1pt with  multiplier = #2 makes:
 15.      \the\dimen1/\the\dimen2.\par
 16. %  \egroup
 17. }
 18. \count1=1
 19. Before fixdimens, count1 = \the\count1.\par
 20. \fixdimens{10}{1000}
 21. \fixdimens{10}{968}
 22. \fixdimens{24}{1044}
 23. After fixdimens, count1 = \the\count1.
Produces: See typeset version.

Comments:

  • The comment on line 1 shows what \fixdimens is supposed to compute.
  • If the product #1*#2 is computed in a \dimen register, the result can easily overflow the register (i.e., be larger than 16384pt). So, line 6 moves \dimen1 to \count1, and the calculations on lines 7-8 are done using \count registers. The result is moved back to \dimen1 by line 9. The trailing sp means use the dimension scaled points with the value in \count1.
  • Lines 18 and 23 show that \fixdimens changed the value of \count1. If the comments on lines 3 and 16 are removed, the register is unchanged.
  • The \division reference page shows a variation of this example.
TeXbook References: 118. Also: 118-119, 218, 276, 349, 391, 398.

Related Primitives: advance, divide, count, dimen, skip, muskip.

For Additional Examples, see: / (italic correction), day, divide, ifnum, time, year

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

muskip Math (Registers)
Internal Quantity
Synopsis: \muskip<8-bit register number>=<muglue>

Description:

    THERE are 256 muskip registers: \muskip0 to \muskip255. Each may hold <muglue>. The commands \advance, \multiply, and \divide allow limited arithemetic with the registers. Unlike the skip registers, a muskip register may not be placed in a dimen register since math glue is not compatible with regular glue [nr]. The muskip registers obey TeX's grouping structure. So, changes to a register inside a group will not affect the value of the register outside the group unless \global is used with the register [119]. The command \showthe\muskip n writes the value for \muskip n to the terminal and to the log file [121]. The register \muskip255 is available for temporary storage [122].
Example:

  1. \muskip1=30mu plus20mu minus10mu % Do not use in, pt, ...
  2. \muskip2=40mu plus1fil %           fil, fill, filll work.
  3. Hello $a\mskip\muskip1 b\mskip\muskip2 c$ World.
  4. %\dimen1=\muskip1 % Warning, this generates a run-time error.
  5. %\count1=\muskip1 % Warning, this generates a run-time error.
  6. %\muskip1=\count1mu % This works but is of dubious value.
Produces: See typeset version.

Comments:

  • Lines 1-2 show examples using \muskip registers. TeX generates a run-time error if a finite unit other than mu is used. Line 2 shows that infinite units may be used with the \muskip registers. The \parfillskip reference page explains why `World' is not flush right.
  • Line 3 doesn't display any useful mathematics, but it illustrates \mskip.
  • Finally, lines 4-5 show things to avoid, and line 6 shows something of little utility.
TeXbook References: 118, 168. Also: 118, 168, 271, 276, 349.

Related Primitives: muskipdef, advance, multiply, divide, dimen.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

muskipdef Math (Registers)
Command
Synopsis: \muskipdef<name>=<8-bit register number>

Description:

    A muskip register may be used directly (e.g., \muskip19=6mu) [118] or indirectly in one of two ways. Each indirect way involves setting up a symbolic name for a register (e.g., \tempmuskip). The first indirect way uses the primitive \muskipdef (e.g., `\muskipdef\tempmuskip=19'); this makes \tempmuskip equivalent to \muskip19. So, the command `\tempmuskip=6mu' sets up muglue that might be used with \mskip [119]. The second indirect way uses the Plain TeX command \newmuskip (e.g., `\newmuskip\tempmuskip'). This time the control sequence \tempmuskip is a muskip register, but it is not at all apparent which one (the log file should contain a line `\tempmuskip=\muskip n for some n) [121]. The direct method is fine for registers used locally in a macro or in a group. The \newmuskip method (or something equivalent if Plain TeX is not used) is the preferable indirect method. If macros from several sources are used, and two different \muskipdef's use the same register number, the macros may interfere with each other. This type of problem is difficult to track down [nr]. TeX suppresses expansion when it is reading a control sequence that will be defined by a \muskipdef [215].
TeXbook References: 119. Also: 119, 215, 277.

Related Primitives: muskip.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

newlinechar Character
-1 * Parameter (integer)
Synopsis: \newlinechar

Description:

    A \write command writes a line to a file or the terminal. If the line is too long, TeX or the operating system may be unable to write it. There are two solutions to this potential problem: break the line into several shorter ones; or give \newlinechar a value and place that value at appropriate places in the line. If \newlinechar is less than 0 or greater than 255, only the first solution given above may be used [228]. The \message command often uses \newlinechar to add line breaks to material written to the log file [nr].
TeXbook References: 228. Also: 228, 273, 348.

Related Primitives: write, message, endlinechar, escapechar.

For Additional Examples, see: message, pagedepth

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

noalign Tables
Command
Synopsis: \noalign{<vertical/horizontal mode material>}

Description:

    THIS command inserts <vertical mode material> in a table begun with \halign. The command should follow a \cr or a \crcr. The material is placed without alignment between the rows in the table. Definitions inside the braces of \noalign are local to that group [237]. For example \noalign{\hrule} inserts a rule between the rows of a table [246]. With \valign, the command inserts <horizontal mode material> between the columns of the table [249].
Example:

  1. \def\tf#1{\omit\hfil #1\hfil}
  2. \def\strutA#1#2{\vrule height#1 depth#2 width0pt}
  3. \offinterlineskip
  4. \def\er{\cr\noalign{\hrule}}
  5. \vbox{\halign
  6. {\strutA{8.5pt}{3.5pt}\vrule#&\kern0.5em#\hfil\quad&\vrule#&\quad\hfil#\quad&
  7. \vrule#&\quad\hfil#\quad&\vrule#&\quad\hfil#\kern0.5em&#\vrule\span\er
  8. \omit\strutA{10.5pt}{3.5pt}\vrule&\multispan7\hfil 1970 Federal Budget
  9.  Transfers\hfil&\cr
 10. \omit\strutA{8.5pt}{4.5pt}\vrule&\multispan7\hfil\selffamily AG (in billions
 11.  of dollars)\hfil&\er
 12. \omit\strutA{3pt}{0pt}\vrule&\multispan7&\er
 13. &\tf{State}&&\tf{Taxes}&&\tf{Money}&&\tf{Net}&\cr
 14. &&&\tf{collected}&&\tf{Spent}&&&\er
 15. \omit\strutA{10.5pt}{3.5pt}\vrule&New York&&   22.91&& 21.35&& -1.56&\cr
 16. &New Jersey&&  8.33&&  6.96&& -1.37&\cr
 17. &Connecticut&& 4.12&&  3.10&& -1.02&\cr
 18. &Maine&&       0.74&&  0.67&& -0.07&\cr
 19. &California&& 22.29&& 22.42&& +0.13&\cr
 20. &New Mexico&&  0.70&&  1.49&& +0.79&\cr
 21. &Georgia&&     3.30&&  4.28&& +0.98&\cr
 22. &Mississippi&& 1.15&&  2.32&& +1.17&\cr
 23. \omit\strutA{8.5pt}{5.5pt}\vrule&Texas&&       9.33&& 11.13&& +1.80&\er
 24. }}
Produces: See typeset version.

Comments:

  • This example continues a multi-reference page example of a table. The previous version is on the \omit reference page.
  • This version adds all the horizontal lines that will appear in the final version. Each horizontal line in the table is added by changing a \cr to \er which is defined on line 4. Note the use of \span on line 7. It expands \er thereby placing a \cr at the end of the preamble. The \crcr reference page shows another way to fix the preamble.
  • Line 12 adds a second horizontal rule which helps divide the header material into two parts. A custom \strutA is used to position the rule at the desired distance below the first one.
  • Also, custom \strutA's are placed at other strategic places in the table (lines 8, 10, 15, and 23). Each provides a small amount of additional space between the rule and following or preceeding text.
  • The example is concluded on the \halign reference page.
TeXbook References: 237. Also: 176, 191, 193, 237, 246, 249, 282, 285-286.

Related Primitives: halign, cr, crcr, valign.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

noboundary Paragraph
Command
Synopsis: \noboundary

Description:

    This command provides one way to break ligatures.
Example:

     fi\hskip 0.75in
     f\noboundary i\hskip 0.75in
     \char102 i\hskip 0.75in
     \char102\char105\hskip 0.75in
     \char102\noboundary\char105
Produces: See typeset version.

Comments:

  • The example shows several combinations of the letters f and i. Each example containing \noboundary breaks the normal `fi' ligature.
TeXbook References: 286. Also: 283, 286, 290.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

noexpand Macro
Command
Synopsis: \noexpand<token>

Description:

    THE expansion of \noexpand<token> is just <token> [213]. Thus, this command provides a way to suppress expansion of a token in situations where TeX normally expands it [nr].
Example:

  1. \def\tmklabel#1#2%
  2. {%
  3.      \write\twaux
  4.      {%
  5.           \noexpand\def
  6.           \expandafter\noexpand
  7.           \csname #1\endcsname
  8.           {#2}%
  9.      }%
 10. }
 11. \tmklabel{junkA}{\the\pageno}
Produces: See typeset version.

Comments:

  • Lines 6-7 cause TeX to save \noexpand and build a control sequence (\cs) using parameter 1.
  • The whatsit\mkindex{whatsit`5`file I/O} created by the \write on line 3 will contain `\noexpand\cs'.
  • When the write takes place, the \noexpand prevents TeX from expanding \cs.
  • Assuming \escapechar is `\', line 11 causes TeX to write the following to the file associated with \twaux: `\def \junkA {xxx}'. Only, TeX will write the current page number instead of xxx.
TeXbook References: 213, 216. Also: 209, 213, 215, 216, 348, 377, 424.

Related Primitives: afterassignment, aftergroup, expandafter, futurelet.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

noindent Paragraph
Command
Synopsis: \noindent

Description:

    IF TeX is in vertical or internal vertical mode, this command begins horizontal mode. This provides a way to begin a new paragraph which is not indented [86]. Otherwise, the command has no effect [286 and 291].
Example:

  1. \parindent=2pc
  2. \indent |\indent| provides one way to start a new paragraph.\par
  3. \indent Also, it can \indent add space anywhere in the paragraph.\par
  4. \noindent |\noindent| also starts a paragraph, but it does not do
  5. the \noindent indent or anything in a paragraph.\par
  6. Finally, |\par| provides a way to end a paragraph that is not followed by a blank line.
Produces: See typeset version.

Comments:

  • The example, together with what it produces, illustrates: \indent, \noindent, and \par.
  • In particular, lines 2-5 show that an \indent in the middle of a paragraph adds space, but a \noindent in the middle of a paragraph does nothing.
TeXbook References: 86. Also: 86, 188, 262-263, 283, 286, 291, 340-341, 355, 419.

Related Primitives: indent.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

nolimits Math
Command
Synopsis: \nolimits

Description:

    SEVERAL math symbols such as summation and integration often appear with subformulas as subscripts and superscripts. The subformulas may be typeset either above and below or to the right of the symbol. Normal mathematical conventions use the first method for most displayed expressions and the second for most in-line expressions. TeX's conventions use the first method in display style and the second method in text style. TeX has three commands which change these conventions: \limits always uses the first method; \nolimits always uses the second method; and \displaylimits uses TeX's normal conventions. If two or more of these commands follow each other, the last one controls how the expression is typeset [144]. Each of these commands must follow a large operator (class 1). Otherwise, TeX generates an error [292].
Example:

  1. \mathchardef\Intop="1352
  2. \mathchardef\Sum="1350
  3. \def\tint{\Intop\nolimits}
  4. \def\tsum{\Sum}
  5. \def\tf#1#2#3%
  6. {%
  7.      $$\hbox{$#2_0^1 3x^2 = x^3]_0^1 = 1$}%
  8.           \hbox{ and $#3^\infty_{n=0}{1\over2^n} = 2$}%
  9.           \kern2pc
 10.           #2_0^1 3x^2 = \left. x^3\right]_0^1 = 1
 11.           \kern2pc
 12.           #3^\infty_{n=0}{1\over2^n} = 2
 13.           \kern1pc
 14.           \leqno{#1.}
 15.      $$
 16. }
 17. \tf 1{\tint}{\tsum}
 18. \tf 2{\tint\nolimits}{\tsum\nolimits}
Produces: See typeset version.

Comments:

  • Lines 1-4 are adapted from Plain TeX [358]. They setup symbols for summation and integration. The integral symbol includes \nolimits because that is how integrals normally appear.
  • Lines 5-16 define a macro which mixes in-line math with display math.
  • Line 17 calls \tf using \tint and \tsum. This typesets each expression as it was intended to be typeset.
  • Line 18 makes a similar call only each symbol is followed by \nolimits. The first three expressions stay the same, but the last one is changed.
  • The `]' displayed by line 10 looks too small to me. The \limits reference page shows an alternate way to typeset it, and I prefer the size shown there.
TeXbook References: 144. Also: 144, 159, 292, 358, 361.

Related Primitives: limits, displaylimits, textstyle, displaystyle.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

nonscript Math
Command
Synopsis: \nonscript

Description:

    THIS command inserts a special glue item of width zero in the current math list. Later, when TeX typesets the math list, TeX will ignore the item immediately after the \nonscript glue if that item is a kern or glue and if the \nonscript item appears in script style or scriptscript style [179].
Example:

  1. \def\tfn#1%
  2. {%
  3.      {2\over\sqrt 5\nonscript#1 + #1 1} =
  4.      {\sqrt 5 #1 -\nonscript#1 1\over 2}
  5. }
  6. $\tfn{\kern1pt}  \hbox{\quad vs\quad}
  7.  \tfn{\kern10pt}$
  8. $$\tfn{\kern1pt} \hbox{\quad vs\quad}
  9.   \tfn{\kern10pt}$$
Produces: See typeset version.

Comments:

  • The macro \tfn defined on lines 1-5 typesets a basic identity containing provision for extra glue.
  • Lines 6-9 call \tfn in both math and display math modes and use two different values for the glue. The numerator and denominator of each fraction made by lines 6-7 have styles S and S'. So, the glue preceeded by \nonscript is removed. On lines 8-9 the styles are T and T' and the glue is left.
TeXbook References: 179. Also: 179, 290, 442, 446.

Related Primitives: scriptstyle, scriptscriptstyle.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

nonstopmode Debugging
Command
Synopsis: \nonstopmode

Description:

    NORMALLY, when TeX discovers an error in a file, it stops processing, displays a message on the terminal, and waits for instructions for what to do next. One option at this point is to press R (run without stopping). That tells TeX to continue processing without stopping if further errors arise. Normal error messages continue to be written to the terminal [31]. If TeX encounters \nonstopmode in a file, then it begins to process the file just as if R was entered in response to an error. This is a global change which continues until the end of the file or until one of the other `..mode' commands is encountered [32]. Certain errors cause TeX to stop processing prematurely in \nonstopmode (e.g., a missing file on an \input statement) [299].
Example:

  1. \nonstopmode
  2.   .
  3.   .
  4.   .
  5. \errorstopmode
Produces: See typeset version.

Comments:

  • If TeX encounters errors on lines 2-4, it writes an error message to the log file and displays a message on the terminal, but it won't stop for user input.
  • After line 5 TeX resumes normal error processing.
TeXbook References: 32. Also: 32, 277, 299.

Related Primitives: batchmode, errorstopmode, scrollmode.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

nulldelimiterspace Math (Kern)
1.2pt * Parameter (dimen)
Synopsis: \nulldelimiterspace<dimen>

Description:

    THIS parameter is used in two ways. First, several commands that require a delimiter allow a period to be used instead of a delimiter. The period means ``do not use a delimiter this time'' (e.g., `\right.'). TeX calls the period a null delimiter [150]. Second, if TeX searches for a delimiter but can't find it (e.g., because the specified font does not have the specified character), TeX treats the delimiter as a null delimiter. In either case this parameter tells TeX how much space to skip for the null delimiter [442].
Example:

  1. \def\tfn#1{\everymath{\nulldelimiterspace=#1}$y = {1\over2}x^2$\quad}
  2. \tfn{0pt}
  3. \tfn{0.5pt}
  4. \tfn{1pt}
  5. \tfn{1.2pt}
  6. \tfn{1.4pt}
  7. \tfn{5pt}
  8. \tfn{10pt}\vskip0.5\baselineskip
  9. \def\tbox#1#2#3#4%
 10. {%
 11.      \everydisplay{\nulldelimiterspace=#4}
 12.      \setbox#1=\vbox{\hsize=1.75in$$#2\sum_{n=0}^\infty {1/2^n}#3^2 = 4$$}
 13. }
 14. \def\tdela{\delimiter"43FA3FB }% made a typo, no such chars exist.
 15. \def\tdelb{\delimiter"53FC3FD }
 16. \tbox1{\left\tdela}{\right\tdelb}{1.2pt}
 17. \tbox2{\left\tdela}{\right\tdelb}{10pt}
 18. \def\tdela{\delimiter"462833A }% a space or \relax is mandatory!
 19. \def\tdelb{\delimiter"562933B }
 20. \tbox3{\left\tdela}{\right\tdelb}{10pt}
 21. \hbox to \hsize{\box1\hfil\box2\hfil\box3}
 22. \everydisplay{}\everymath{}
Produces: See typeset version.

Comments:

  • Lines 1-8 typeset the same expression using different values for \nulldelimiterspace and illustrate the first type of null delimiter. Recall that \over is equivalent to `\overwithdelims..' [152].
  • Lines 16-17 use the macro \tbox defined on lines 9-13 and the two delimiters defined on lines 14-15 to typeset an expression. The delimiters refer to characters which do not exist (e.g., "3FA). These lines illustrate the second type of null delimiter.
  • Lines 18-19 make correct definitions for the two delimiters and line 20 typesets the expression again. This time the large value passed as parameter 4 to \tbox has no effect.
TeXbook References: 150. Also: 150, 274, 348, 442.

Related Primitives: left, right, abovewithdelims, delimiter.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

nullfont Fonts
Internal Quantity
Synopsis: \nullfont

Description:

    THIS quantity stands for a font with no characters. It is present in every document [14]. In math mode TeX works with up to sixteen font families each containing three fonts. TeX sets each undefined family member to \nullfont [153]. This font comes with the seven required \fontdimen parameters (each is zero). Additional parameters may be assigned provided no other fonts have been loaded [433].
TeXbook References: 14, 153. Also: 14, 153, 271, 433.

Related Primitives: font, fontdimen.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

number Character
Command
Synopsis: \number<number>

Description:

    THIS command produces the decimal equivalent of <number> [40]. It suppresses leading zeros and may be used with internal registers or parameters [41]. It produces characters which have category code 12 (other) or 10 (space) [214].
Example:

  1. \number 01234\par
  2. \number 0\par
  3. \number-0123\par
  4. \number 18.23\par
  5. \number\month/\number\day/\number\year\par% make today's date.
  6. \setbox0=\hbox{Hello World}
  7. \noindent\copy0: \number\wd0, \the\wd0\par
  8. \setbox0=\hbox to 20pt{\hss}
  9. \noindent\copy0: \number\wd0, \the\wd0\par
Produces: See typeset version.

Comments:

  • Lines 1-3 show TeX is intelligent about not printing a leading zero.
  • Line 4 shows \number works with decimals.
  • Line 5 shows one way to get today's date.
  • Lines 6-9 show that \number displays a <dimen> variable in scaled points (65536sp = 1pt).
  • The \noindent at the start of lines 7 and 9 is required to make TeX treat each line as a single paragraph.
TeXbook References: 40-41. Also: 40-41, 213, 214, 252, 406, 424.

Related Primitives: romannumeral.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

omit Tables
Command
Synopsis: \omit

Description:

    IF \omit is the first command in an entry of a table, TeX does not use the template specified in the table's preamble\mkindex{preamble} for the entry. Instead, TeX uses # as the template. This provides a way to customize an individual entry in the table [240]. Frequently, \omit is combined with \span to provide a custom template which spans two or more columns. The Plain TeX macro \multispan makes it easy to span a specified number of columns with custom material [243].
Example:

  1. \def\tf#1{\omit\hfil #1\hfil}
  2. \def\strutA#1#2{\vrule height#1 depth#2 width0pt}
  3. \offinterlineskip
  4. \vbox{\halign
  5. {\strutA{8.5pt}{3.5pt}\vrule#&\kern0.5em#\hfil\quad&\vrule#&\quad\hfil#\quad&
  6. \vrule#&\quad\hfil#\quad&\vrule#&\quad\hfil#\kern0.5em&#\vrule\cr
  7. &\multispan7\hfil 1970 Federal Budget Transfers\hfil&\cr
  8. &\multispan7\hfil (in billions of dollars)\hfil&\cr
  9. &\tf{State}&&\tf{Taxes}&&\tf{Money}&&\tf{Net}&\cr
 10. &&&\tf{collected}&&\tf{Spent}&&&\cr
 11. &New York&&   22.91&& 21.35&& -1.56&\cr
 12. &New Jersey&&  8.33&&  6.96&& -1.37&\cr
 13. &Connecticut&& 4.12&&  3.10&& -1.02&\cr
 14. &Maine&&       0.74&&  0.67&& -0.07&\cr
 15. &California&& 22.29&& 22.42&& +0.13&\cr
 16. &New Mexico&&  0.70&&  1.49&& +0.79&\cr
 17. &Georgia&&     3.30&&  4.28&& +0.98&\cr
 18. &Mississippi&& 1.15&&  2.32&& +1.17&\cr
 19. &Texas&&       9.33&& 11.13&& +1.80&\cr
 20. }}
Produces: See typeset version.

Comments:

  • This example continues a multi-reference page example of a table. The previous version is on the \cr reference page.
  • This version adds all the vertical lines that will appear in the final version. All the changes inside the \halign occur in the preamble (lines 5-6). In addition, lines 2 and 3 are new.
  • Five columns were added to the table (one on each end and one between each of the original columns). A vertical rule is placed in each new column. Extra space is placed to the right of the first rule and to the left of the last rule. The height and depth of the rules are controlled by \strutA (line 2), and \offinterlineskip (line 3) is used to turn off normal line spacing.
  • The final version of the table is on the \halign reference page, and the next version is on the \noalign reference page.
TeXbook References: 240, 243-244. Also: 240, 243-244, 246-247, 282.

Related Primitives: halign, span, valign.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

openin File I/O
Command
Synopsis: \openin<4-bit number>=<file name>

Description:

    THIS command opens a file for input. The file may then be read a line at a time using \read or a test may be made which will tell if the file actually exists or not. The number must be between 0 and 15. Plain TeX has a \newread command which allocates input numbers [216]. Most TeX implementations add the extension `.tex' to the file name if the name does not have an extension. If the file cannot be found, TeX does not issue an error message. The \closein command closes the file [217].
Example:

  1. %\newread\traux%  These appear uncommented in my formatting file
  2. %\newwrite\twaux
  3. \def\tfilecheck#1%
  4. {%
  5.      \openin\traux=#1\relax
  6.      File ``#1'' %
  7.      \ifeof\traux
  8.           \closein\traux
  9.           does not exist.
 10.      \else
 11.           \closein\traux
 12.           exists.
 13. %         \input #1 %    This is a test. Don't really input the file.
 14.      \fi
 15.      \par
 16. %    \openout\twaux=#1 % This is a test. Don't really open  the file.
 17. }
 18. \tfilecheck{junk}
 19. \tfilecheck{trechar}
 20. \tfilecheck{trechar.tex}
 21. \tfilecheck{\jobname.tmp}
Produces: See typeset version.

Comments:

  • Frequently, a document prepares one or more auxilary files which are used to typeset a special part of the document (e.g., the table of contents or the index). Each time TeX process the document, it loads (via \input) the current version of each auxilary file, and it creates a new version of each file.
  • A routine similar to \tfilecheck is used to load an auxilary file. The routine prevents the error message that results if TeX can't find a file which should be loaded.
  • Lines 18-21 illustrate a potential trap involving file names and extensions. There is no file named trechar on the author's system, but there is a file named `trechar.tex'. Similarly, there is a file named junk, but there is no file named `junk.tex'. The message made by line 19 is wrong because TeX tried the \openin on line 5 twice. First, it tried trechar which failed; then it tried `trechar.tex' which succeeded.
TeXbook References: 216-217. Also: 216-217, 280.

Related Primitives: closein, read, input.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

openout File I/O
Command
Synopsis: \openout<4-bit number>=<file name>

Description:

    THIS command opens a file for output. The number must be between 0 and 15. Most TeX implementations add the extension `.tex' to the file name if the name does not have an extension. The \closeout command closes the file [226]. Plain TeX has a \newwrite command which allocates output numbers. Unless \openout is preceeded by \immediate, TeX places the command in a whatsit\mkindex{whatsit`5`file I/O} item in the current list and delays opening the file until a \shipout encounters the list. TeX preserves the order of output commands unless insertions or something similar cause boxes to be written out of order [227]. An \openout whatsit, which occurs in a box governed by leaders, is ignored [228].
Example:

     \openout\twaux=junkjunk.tex\relax
     \write\twaux{{\noexpand\bf byebye}\ World}
     \closeout\twaux
Produces: See typeset version.

Comments:

  • This gives a simple example of the three output commands: \openout, \write, and \closeout. The three lines make a file which has a single line.
  • The \noexpand places the TeX command \bf at the start of the line.
  • The \closein reference page loads and typesets junkjunk.tex.
TeXbook References: 226-228. Also: 226-228, 254, 280, 422, 423.

Related Primitives: closeout, write, immediate.

For Additional Examples, see: openin

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

or Logic
Command
Synopsis: \or

Description:

    This command separates the cases in an \ifcase conditional construction [210].
Example:

  1. \def\sillyor#1#2%
  2. {%
  3.      #1. Value is: %
  4.      \ifcase #2 %
  5.           A% 0 case
  6.      \or
  7.           B% 1 case
  8.      \or
  9.           C% 2 case
 10.      \or
 11.           D% 3 case
 12.      \else
 13.           hard to say% everything else.
 14.      \fi
 15.      .\par
 16. }
 17. \sillyor1{-15}
 18. \sillyor2{0}
 19. \sillyor3{2}
 20. \sillyor4{4}
 21. \sillyor5{0.7071}% (2^.5)/2.
 22. \sillyor6{3.14159}
Produces: See typeset version.

Comments:

  • This example appears silly until the results for lines 21 and 22 are examined.
  • They show that TeX processes an \ifcase statement in two steps. First, TeX reads characters after \ifcase until one appears which cannot be part of an integer (e.g., the decimal on lines 21 and 22). Then, TeX does the case.
  • Line 21 typesets everything after the 0 to the first \or which is on line 6. In particular, this includes the `.7071' which will be on line 4.
  • Line 22 typesets the material after the third \or which is on line 10. So, the `.14159' on line 4 is skipped!
TeXbook References: 210. Also: 210, 213, 406.

Related Primitives: ifcase, else.

For Additional Examples, see: else

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

outer Macro
Command
Synopsis: \outer<macro-definition assignment>

Description:

    A macro may be declared \outer if the macro should not be allowed in: a) the argument, the parameter text, or the replacement text of another macro; b) the preamble of an alignment; or c) conditional text. The three prefixes (\outer, \global, and \long) can be applied to \def in any order, and they can appear more than once [206]. If two tokens compared by \ifx are macros, TeX includes each token's status with respect to \outer in deciding if the two are the same or not [210].
TeXbook References: 206. Also: 206, 210, 275, 354, 357, 418-419, 422.

Related Primitives: def, edef, gdef, xdef, global, long.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

output File I/O
{\shipout\box255} * Parameter (token)
Synopsis: \output{<token list>}

Description:

    EACH time TeX completes a page, it puts the page in \box255 and calls the current \output routine. Normally, the output routine adds a page header and footer, positions insertions such as footnotes, and maintains the current page number. However, if no output routine is specified or the <token list> is empty, TeX uses the default routine `\shipout \box255' which writes the page to the dvi file without a header, footer, or page number. TeX automatically begins a new level of grouping when it starts the output routine [253]. Just before the output routine begins, TeX sets \insertpenalties to the number of insertions that were held over to the next page. Also, it sets \outputpenalty to the penalty at the breakpoint used to make the page [254]. Finally, TeX increases \deadcycles by 1 and checks if \deadcycles is larger than \maxdeadcycles. If it is, TeX writes an error message to the log file and uses the default output routine. At the end of the output routine TeX complains if \box255 is not empty. Also, it complains if \box255 is not empty when it puts the newly completed page in that box just before the output routine starts [255].
TeXbook References: 253-257. Also: 125, 253-257, 275, 364, 370, 417.

Related Primitives: shipout, outputpenalty, insertpenalties, deadcycles.

For Additional Examples, see: vsize

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

outputpenalty Penalties
Parameter (integer)
Synopsis: \outputpenalty

Description:

    PART of the cleanup that TeX does, after a page break is determined but before the output routine is called, is to set \outputpenalty. If the page break occurred at a penalty, that penalty is placed in \outputpenalty. Otherwise, \outputpenalty is set to 10,000 [125]. An output routine which ships out nothing and returns everything in \box255 to the main vertical list should also insert a penalty whose value is \outputpenalty [254]. Normally, an output routine has no idea where it is in a document. However, if special penalties are placed in the document, the output routine can check \outputpenalty and get clues about where it is and what triggered the page break [400].
TeXbook References: 125, 254. Also: 125, 254-255, 273, 349, 400, 417.

Related Primitives: penalty, insertpenalties.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

over Math
Derived Command
Synopsis: \over

Description:

    THIS command places one subformula over a second subformula and puts a line between the two [139]. The command is an abbreviation for `\overwithdelims..' [152].
Example:

     ${1 \over 2} + {2 \over 3} = {5 \over 6}$,
     ${a \over b} + {c \over d} = {{a*d}+{b*c} \over {b*d}} = {(a*d + b*c) / (b*d)}$
     \par\vskip0.5\baselineskip
     $x + y^{2\over k+1}$ or
     $x + y^{2/(k+1)}$, which is better?\par\vskip0.5\baselineskip
     ${a+1\over b+1}x$ or
     $\bigl((a+1) / (b+1)\bigr)x$ or
     $(a+1)x / (b+1)$ or
     $(ax+x) / (b+1)$, which is better?
Produces: See typeset version.

Comments:

  • These lines show several fractions build using \over.
  • Fractions may also be written in slashed form. Both forms may need to be tried before one is selected.
  • Note the two sizes of parenthesis used on the last typeset line.
TeXbook References: 139, 152. Also: 139-141, 148, 152, 292, 437, 444-445.

Related Primitives: atop, above, overwithdelims.

For Additional Examples, see: above, hfill, hfilneg

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

overfullrule Box
5pt * Parameter (dimen)
Synopsis: \overfullrule

Description:

    THIS parameter determines the width of the vertical rule placed at the end of overfull boxes [274]. The rule is not present in underfull boxes or if \overfullrule=0pt [307].
Example:

     \def\overfullboxes#1#2% text to check & typeset; width of overfullrule.
     {%
       \bgroup
          \overfullrule=#2%
          \setbox0=\hbox spread -1em{#1}%
          \count12=\the\badness
          \hbox to 2.5in{\box0\hfil\the\count12}%
       \egroup
     }
     \overfullboxes{The badness of this line is: }{15pt}
     \overfullboxes{The badness of this line is: }{5pt}%  This is default value.
     \overfullboxes{The badness of this line is: }{0.5pt}
     \overfullboxes{The badness of this line is: }{0pt}
Produces: See typeset version.

Comments:

  • Parameter 2 of \overfullboxes gives the width of \overfullrule.
TeXbook References: 274. Also: 274, 307, 348.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

overline Math
Command
Synopsis: \overline<character or {subformula}>

Description:

    THIS command places a line over the following character or subformula [131]. The command changes one of the uncramped styles to its corresponding cramped style [141].
Example:

     \def\ta{\overline}
     To summarize: if $ x + y = z$,
     $\ta x + \ta y = \ta z $
      and $\ta{x^2} + \ta{y^2} = \ta{z^2}$,
      then $\ta{\ta{x^2} + \ta{y^2}} = \ta{\ta{z^2}}$.\par
     Of course, $ \ta l + \ta m \ne \ta i$.
Produces: See typeset version.

Comments:

  • The line is positioned appropriately for the height and width of the material it covers.
TeXbook References: 130-131. Also: 130-131, 136, 141, 170, 291, 443.

Related Primitives: underline.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

overwithdelims Math
Derived Command
Synopsis: \overwithdelims<delim1><delim2>

Description:

    THIS command is a generalized form of \over. It builds the same fraction \over does. Then it puts <delim1> before the fraction and <delim2> after it. Both delimiters are scaled appropriately. If a `.' is used for either delimiter, TeX ignores the corresponding delimiter. In fact, \over is an abbreviation for `\overwithdelims..'. Also, \overwithdelims is derived from \abovewithdelims [152].
Example:

  1. \def\legendre{\overwithdelims()}
  2. \def\euler{\overwithdelims\langle\rangle}
  3. $a \legendre p$ and $a \euler b$\par
  4. If $p$ is an odd prime and $a$ is any number not divisible by $p$,
  5. then Legendre's symbol $a\legendre p$ is defined by:
  6. $$\eqalign{{a\legendre p} = +1\hbox{,\quad if\quad}a\hbox{\ R }p,\cr
  7.            {a\legendre p} = -1\hbox{,\quad if\quad}a\hbox{\ N }p.\cr}$$
Produces: See typeset version.

Comments:

  • Lines 1-2 define control sequences appropriate for Legendre and Euler symbols.
  • Line 3 gives a simple example of each one.
  • Lines 4-7 define the Legendre symbol. Omitted is a definition of `a R p' and `a N p'. They mean: a either is or is not a quadratic residue of p.
TeXbook References: 152. Also: 152, 292, 444-445.

Related Primitives: over, abovewithdelims.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

pagedepth Page
Internal Quantity
Synopsis: \pagedepth

Description:

    AS TeX adds material (e.g., boxes, inserts, kerns, or glue) to the current page, the height and depth of the page constantly changes. TeX stores the current depth in \pagedepth [114]. The value will be no larger than \maxdepth [113] which in Plain TeX is 4pt [348].
Example:

  1. \newlinechar=`@     % makes \message{} start on a new line.
  2. %
  3. \everypar={\tpageitems}
  4. \parskip=1pt plus-2.02filll minus3pt
  5. %
  6. \def\tpageitems
  7. {%
  8.      \message
  9.      {
 10.           p1=\the\pagetotal;
 11.           p2=\the\pagegoal;
 12.           p3=\the\pagedepth;
 13.           p4=\the\pagestretch;
 14.           p5=\the\pageshrink;
 15.           p6=\the\pagefilstretch;
 16.           p7=\the\pagefillstretch;
 17.           p8=\the\pagefilllstretch @
 18.      }%
 19. }
Produces: See typeset version.

Comments:

  • The above example shows one way to study the 8 `page...' items.
  • Lines 6-19 define the macro \tpageitems. It writes a line in the log file which holds the current value of each `page...' item.
  • The `@' on line 17 works with line 1 to make each message appear on its own line.
  • Line 3 causes \tpageitems to be called at the start of every paragraph.
  • Line 4 places strange glue between paragraphs. By changing the values on line 4 and adding \vskips between paragraphs, it is possible to see what the `page...' items hold in different situations.
TeXbook References: 114, 123. Also: 114, 123, 214, 271.

Related Primitives: maxdepth, pagegoal, pagetotal, pagestretch, pageshrink, pagefilstretch, pagefillstretch, pagefilllstretch.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

pagefilllstretch Page
Internal Quantity
Synopsis: \pagefilllstretch

Description:

    SEVERAL quantities hold a running total of the plus component of all glue added directly to the current page. The filll values are added to \pagefilllstretch [114].
TeXbook References: 114. Also: 114, 214, 271.

Related Primitives: pagefilstretch, pagefillstretch, pagestretch, pageshrink, pagegoal, pagetotal, pagedepth, tracingpages.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

pagefillstretch Page
Internal Quantity
Synopsis: \pagefillstretch

Description:

    SEVERAL quantities hold a running total of the plus component of all glue added directly to the current page. The fill values are added to \pagefillstretch [114].
TeXbook References: 114. Also: 114, 214, 271.

Related Primitives: pagefilstretch, pagefilllstretch, pagestretch, pageshrink, pagegoal, pagetotal, pagedepth, tracingpages.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

pagefilstretch Page
Internal Quantity
Synopsis: \pagefilstretch

Description:

    SEVERAL quantities hold a running total of the plus component of all glue added directly to the current page. The fil values are added to \pagefilstretch [114].
TeXbook References: 114. Also: 114, 214, 271.

Related Primitives: pagefillstretch, pagefilllstretch, pagestretch, pageshrink, pagegoal, pagetotal, pagedepth, tracingpages.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

pagegoal Page
Internal Quantity
Synopsis: \pagegoal

Description:

    THIS quantity holds the desired height of the current page. Before the first box is added to the page, TeX sets \pagegoal to \maxdimen (16383.99998pt). When TeX adds the first box or insertion to the page, TeX changes \pagegoal to \vsize. After that assignment, TeX does not use changes to \vsize until the next page starts. In contrast, \pagegoal may be changed at any time [114].
TeXbook References: 114. Also: 114, 123, 214, 271.

Related Primitives: vsize, pagetotal, pagedepth.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

pageshrink Page
Internal Quantity
Synopsis: \pageshrink

Description:

    THIS quantity holds a running total of the minus component of all glue that is added to the current page [114]. Only finite dimensions may be used in the minus component of such glue. For example, TeX issues a run-time warning if `\vskip 2pt minus 1fil' appears directly on the current page (i.e., not buried in a box) [nr].
TeXbook References: 114. Also: 114, 123, 214, 271.

Related Primitives: pagestretch, pagefilstretch, pagefillstretch, pagefilllstretch, pagegoal, pagetotal, pagedepth, tracingpages.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

pagestretch Page
Internal Quantity
Synopsis: \pagestretch

Description:

    SEVERAL quantities hold a running total of the plus component of all glue added directly to the current page. The finite values are added to \pagestretch. In contrast to \pageshrink the plus component of glue on the current page may hold one of the special units fil, fill, or filll. The corresponding `\pagefil..stretch' holds the total of that glue [114].
TeXbook References: 114. Also: 114, 214, 271.

Related Primitives: pageshrink, pagefilstretch, pagefillstretch, pagefilllstretch, pagegoal, pagetotal, pagedepth, tracingpages.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

pagetotal Page
Internal Quantity
Synopsis: \pagetotal

Description:

    EACH time TeX adds a box or an insert to the current page, it updates \pagetotal which is the the accumulated height of the page [114].
TeXbook References: 114. Also: 114, 123, 214, 271.

Related Primitives: pagegoal, pagestretch, pageshrink, pagefilstretch, pagefillstretch, pagefilllstretch, pagedepth, tracingpages.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

par Paragraph
Command
Synopsis: \par

Description:

    THIS command provides an explicit way to end a paragraph [86]. However, the command is not allowed in math mode [135] and does nothing in restricted horizontal mode [286]. Also, in vertical mode the command just exercises the page builder [283].
Example:

     \parindent=2pc
     \indent |\indent| provides one way to start a new paragraph.\par
     \indent Also, it can \indent add space anywhere in the paragraph.\par
     \noindent |\noindent| also starts a paragraph, but it does not do
     the \noindent indent or anything in a paragraph.\par
     Finally, |\par| provides a way to end a paragraph that is not followed by a blank line.
Produces: See typeset version.

Comments:

  • The example, together with what it produces, illustrates: \indent, \noindent, and \par.
TeXbook References: 99-100. Also: 47, 86-87, 100, 135, 202, 249, 262, 283, 286, 340, 351, 380-381.

Related Primitives: parfillskip.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

parfillskip Paragraph
0pt plus1fil * Parameter (glue)
Synopsis: \parfillskip=<glue>

Description:

    WHEN TeX ends a paragraph, it adds the following to the current horizontal list: `\unskip\penalty10000\hskip\parfillskip\penalty-10000'. The \unskip removes the glue at the end of the paragraph (e.g., unnecessary trailing spaces). The first penalty prevents a line break, and the second penalty forces a break. Finally, the glue added by \parfillskip finishes the last line of the paragraph [100]. Each implemention of TeX has a limit to the number of words in a paragraph. TeX can work with longer paragraphs by breaking the paragraph into pieces which are within TeX 's limits and connecting the pieces with `{\parfillskip=0pt \par \parskip=0pt \noindent}' [315]. If TeX begins display math mode in the middle of a paragraph, it adds \parfillskip glue to the material which preceeds the display [287].
Example:

     \hsize=4.75in
     \tstory\par% The \adjdemerits reference page holds the definition of \tstory
     \vskip3pt
     {\parfillskip=0ptplus1filll
     \tstory\par}
Produces: See typeset version.

Comments:

  • Near the end of \tstory the following appears: `\kern2em\hfill Fyodor'. The \hfill overpowers the normal \parfillskip glue which includes plus1fil. That is why the last line in the first paragraph ends flush right.
  • But in the second paragraph, the stronger plus1filll overpowers the \hfill and so space only 2em units wide separates `...' from Fyodor.
TeXbook References: 100. Also: 100, 188, 274, 286, 307, 315, 332, 348, 394, 419.

Related Primitives: hsize, parindent, par.

For Additional Examples, see: predisplaysize

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

parindent Paragraph
20pt * Parameter (dimen)
Synopsis: \parindent=<dimen>

Description:

    THIS dimension gives the width of the empty box which is placed at the start of each new paragraph not started by \noindent [86]. TeX adds the box to the paragraph before it adds the tokens in \everypar [105]. Also, it uses the value \parindent has when the box is added to the current horizontal list [101].
Example:

     \hsize=4.75in
     \parskip=6pt% The \adjdemerits reference page holds the definition of \tstory
     \parindent=2pc\tstory\par
     \parindent=1pc\tstory\par
Produces: See typeset version.

Comments:

  • This example shows two different indentations and uses \parskip to add space between the paragraphs.
TeXbook References: 86, 101. Also: 86, 100, 101-102, 105, 262, 274, 282, 286, 291, 342, 348, 355, 394, 406, 415.

Related Primitives: indent, noindent, hsize, parfillskip.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

parshape Paragraph
Internal Quantity
Synopsis: \parshape=<number><shape dimensions>

Description:

    TEX provides two alternatives to the normal paragraph shape. One is \parshape which allows the lines in a paragraph to have arbitrary indentations (from the left margin) and lengths. The number specifies how many shape dimensions are present. Each shape dimension consists of two dimensions: an indentation and a length. The ith line in the paragraph uses the ith shape dimension if i <= n and the nth otherwise [101]. TeX sets `\parshape=0' at the end of every paragraph [103] and when it enters internal vertical mode. That cancels the effects of a previously specified \parshape [101 and 349]. The command `\the\parshape' only gives the number of shape dimensions [214].
Example:

  1. \hsize=2.5in
  2. \setbox0=\vbox{\parshape=13 0pt 2.5in 0pt 2.5in 0pt 2in 0pt 2in 0pt 2in
  3. 0pt 2.5in 0pt 2.5in 0pt 2.5in 0pt 2.5in  0.5in 2in 0.5in 2in 0.5in 2in 0pt 2.5in
  4. \noindent\vrule height10pt depth0pt width0pt\tstory\par}
  5. \copy0% The \adjdemerits reference page holds the definition of \tstory
  6. \vskip6pt
  7. \splittopskip=10pt
  8. \setbox1=\vsplit0 to 84pt
  9. \setbox2=\vbox to 84pt{\unvbox0\vfill}
 10. \hbox to 5.25in{\box1\hfil\box2}
 11. \nointerlineskip% see page 352 in TTB
 12. \setbox3=\boxit{\hbox{\selffamily AA T\kern-.1667em% The \lower reference
 13.                 \lower.5ex\hbox{E}\kern-.125em X}}%  page shows TeX's logo.
 14. \vbox to 0pt{\kern-57pt\hbox{\kern166pt\box3}\vss}
Produces: See typeset version.

Comments:

  • The \vbox constructed on lines 2-4 begins with a \parshape containing 13 shape dimensions. The \vrule on line 4 is an example of a strut. It positions the first baseline exactly 10 points below the top of the box.
  • The first paragraph, displayed by line 5, looks unusual until the second paragraph, displayed by line 10, is examined.
  • The value given to \splittopskip on line 7 matches the height of the strut from line 4 and forces the baselines in the two columns to line up.
  • Lines 12-13 put TeX's logo (prepared on the \lower reference page) in a box.
  • The technique shown on line 14 may be used to move a box to any place on the page (even outside TeX's page boundaries).
  • Without line 11 the Comments section begins lower on the page than it should.
TeXbook References: 101. Also: 101-103, 214, 271, 277, 283, 315, 349, 374.

Related Primitives: hangafter, handindent, prevgraf.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

parskip Paragraph
0pt plus 1pt * Parameter (glue)
Synopsis: \parskip=<glue>

Description:

    THIS parameter holds glue that is placed between paragraphs. TeX adds it to the vertical list, at the start of a new paragraph, unless that list is empty [104 and 282].
Example:

     \parskip=0.5\baselineskip
     \parindent=0pt
     There are many different paragraph styles. The next few . . .

     One style is to indent the first line of each paragraph but put no extra space between paragraph. Advantages of . . .

     A second style is to start each paragraph flush left and put extra space between paragraphs. This style . . .
Produces: See typeset version.

Comments:

  • The above lines represent the second style referred to in the text of the example.
  • The default \parskip glue works quite well with text consisting of many short paragraphs (e.g., a membership directory) none of which should be split between pages.
  • Note, TeX does not place \parskip glue before the first paragraph.
TeXbook References: 104. Also: 79, 104-105, 262, 274, 282, 342, 348, 355, 406, 417.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

patterns Hyphenation
Command
Synopsis: \patterns{<patterns>}

Description:

    THIS command should only be used in INITEX. It replaces the current set of hyphenation patters for the current language with <patterns> [453]. It generates an error in a production version of TeX [nr].
TeXbook References: 453, 455. Also: 277, 453, 455.

Related Primitives: hyphenation, language.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

pausing Debugging
0 * Parameter (integer)
Synopsis: \pausing

Description:

    IF \pausing is given a positive value, TeX stops after every line of input is read. At that point the line may be edited. If it is, the new line is used for the remainder of the current run. No changes are written to the actual file [303].
Example:

  1. \pausing=1
  2. Line A.\par
  3. Line B.\par
  4. Line C.\par
  5. Line D.\par
  6. Line E.\par
  7. \pausing=0
Produces: See typeset version.

Comments:

  • The \pausing command on line 1 causes TeX to display subsequent lines on the terminal and to allow each line to be changed. In the above example, I only changed line 4. TeX wrote the change to the log file (line 10) and used it to typeset the line.
TeXbook References: 303. Also: 273, 303.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

penalty Penalties
Command
Synopsis: \penalty<number>

Description:

    THIS command adds a penalty item to the current list. In vertical mode TeX exercises the page builder after the item is added [280]. A penalty is one of five places where a line break can occur in a horizontal list [96] and one of three places where a page break can occur in a vertical list [110]. Penalties in both places may be made automatically by TeX or added by the \penalty command. If <number> is 10,000 or larger, TeX will never break a line or a page there. Also, if <number> is -10,000 or less, it will always break a line or a page there [97 and 110]. Any other penalty value is used in the calculation of: a potential line's demerits (in horizontal mode) [98] or a potential page's cost (in vertical mode) [111]. Plain TeX has \break and \nobreak macros which are defined to be: \penalty-10000 and \penalty10000. The macros may be used in any mode [353]. In horizontal mode, the \vadjust command may be used to add a penalty that will show up in the enclosing vertical list [105].
Example:

     \setbox1=\vbox{\hsize=2.25in 1. Hello World. How are you?}
     \setbox2=\vbox{\hsize=2.25in 2. Hello World. How\penalty-10000\ are you?}
     \hbox to 4.75in{\box1\hfil\box2}
Produces: See typeset version.

Comments:

  • Boxes 1 and 2 are the same except for the penalty in box 2. It forces a break, and, since it occurs in horizontal mode, the break is a line break not a page break. This results in an underfull \hbox message in the log file and a spaced out first line.
  • TeX lines up the baselines of \box1 and \box2. That is why there is a blank line before the start of the left paragraph.
TeXbook References: 110-111. Also: 79, 97, 110-111, 174, 280, 353.

Related Primitives: lastpenalty, vadjust.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

postdisplaypenalty Math (Penalties)
0 * Parameter (integer)
Synopsis: \postdisplaypenalty

Description:

    WHEN TeX typesets a math display or an alignment display, it inserts this penalty (in vertical mode) immediately after the list holding items for the display [189-190]. Changes made to \postdisplaypenalty inside a display are local to the display [nr].
TeXbook References: 189-190. Also: 189-190, 272.

Related Primitives: predisplaypenalty.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

predisplaypenalty Math (Penalties)
10000 * Parameter (integer)
Synopsis: \predisplaypenalty

Description:

    WHEN TeX typesets a math display or an alignment display, it inserts this penalty (in vertical mode) immediately before the list holding items for the display. The Plain TeX value means a display will never appear at the top of a page [189-190]. Changes made to \predisplaypenalty inside a display are local to the display [nr].
TeXbook References: 189-190. Also: 189-190, 272, 348.

Related Primitives: postdisplaypenalty, displaywidowpenalty.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

predisplaysize Math (Paragraph)
Parameter (dimen)
Synopsis: \predisplaysize

Description:

    WHEN TeX reads the opening $$ of a display, it sets \predisplaysize to: a) -\maxdimen if the display is the first line in a paragraph, or it follows another display; b) \maxdimen if the glue in the hbox formed by the previous line stretches or shrinks; c) 2 ems in the current (text) font plus the distance the hbox is shifted right plus the position of the right edge of the right most box inside the hbox [188]. TeX uses \predisplaysize in deciding whether to put displayskips or displayshortskips above and below the display [189]. The parameter may be changed inside a display, and TeX uses the last value it encounters in the display [188]. Alignment displays do not use this parameter [190].
Example:

  1. \def\tpds#1#2{\global\setbox#1=\hbox{#2) \the\predisplaysize.
  2.                                             \ \the\parfillskip}}
  3. \bgroup
  4. \parfillskip=330pt% makes rigid glue in this group. See [188] in TTB
  5. {\it The Fundamental Theorem of Integral Calculus.}
  6. Let $f$ be continuous on the interval
  7. $a\le x \le b$. If% becomes line 2! of typeset material. It is stretched.
  8. $$\abovedisplayshortskip=100pt% local to display b).
  9. F(t) = \int_a^t f(x)\,dx,\qquad a\le t \le b,\tpds2b$$         % b)
 10. then $$\abovedisplayskip=100pt% local to display c).
 11. D_tF(t) = f(t).\tpds3c$$                                       % c)
 12. \egroup
 13. $$\hbox{For example, if } F(t) = \int_0^t 3x^2\,dx = t^3
 14.  \hbox{, then }F'(t) = 3t^2.\tpds1a$$                          % a)
 15. \setbox4=\hbox{$a\le x \le b$. If}% No \quads here.
 16. \setbox5=\hbox{then\quad\quad}%     Put 2 \quads here.
 17. \unhbox2. |\wd4| = \the\wd4.\par
 18. \unhbox3. |\wd5| = \the\wd5.\par
 19. \unhbox1. |\hsize| = \the\hsize.\par
Produces: See typeset version.

Comments:

  • This example typesets a single paragraph which holds three displays. Each display illustrates a different option for \predisplaysize.
  • The third display (lines 13-14) is an example of option `a'. It immediately follows the second display which ends on line 11. The results from line 19 verify this and show two related values.
  • The first two displays (lines 8-9 and 10-11) appear to be the same. Each occurs in the middle of the paragraph, and a short line preceeds each one. So, TeX should use displayshortskips before and after each display.
  • But, clearly the first display does not use the value on line 8. This is because the \parfillskip value on line 4 causes the material typeset by line 7 to stretch slightly. The numbers typeset by lines 17 and 19 verify this. Also, the first number typeset by line 17 shows this display is an example of option `b'.
  • The second example looks identical to the first. So, why isn't the value on line 10 used? Luck! A single word (`then') preceeds the display. TeX adds the unusual glue (from line 4) after the word, but TeX can't stretch out the line (it could for `the n' or `then, we see'). The numbers typeset by line 18 show this display is an example of option `c'.
TeXbook References: 188. Also: 188, 190, 274, 349.

Related Primitives: displayindent, displaywidth, abovedisplayskip, abovedisplayshortskip.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

pretolerance Paragraph
100 * Parameter (integer)
Synopsis: \pretolerance=<number>

Description:

    TEX will make up to three attempts to break a paragraph into lines. First, it tries to find breaks, without using hyphenation, so that each of the resulting lines has \badness no larger than \pretolerance. Since \badness is at most 10,000, setting `\pretolerance=10000' will always allow TeX to find line breaks on its first attempt, but the results may be poor. Also, if `\pretolerance=-1', TeX skips the first attempt [96]. The second attempt uses \tolerance [97], and the third attempt uses \emergencystretch [107].
Example:

     \hsize=1.25in\parindent=0pt
     \pretolerance=100
     \tolerance=200
     \emergencystretch=0pt
     \setbox0=\vtop{\tstory\par}% The \adjdemerits reference page holds
     \setbox1=\vtop{\pretolerance=10000 %     the definition of \tstory
     \tstory\par}
     \setbox2=\vtop{\pretolerance=-1\emergencystretch=1.65em
     \tstory\par}
     \hbox to 5.0in{\box0\hfil\box1\hfil\box2}
Produces: See typeset version.

Comments:

  • The paragraph on the left uses default values for \pretolerance, \tolerance, and \emergencystretch. It has numerous overfull boxes.
  • The middle paragraph sets \pretolerance to its maximum value. Although the overful boxes go away, a number of lines are quite poor. Notice, none of the lines are hyphenated!
  • The paragraph on the right sets \emergencystretch to 1.65em (several values were tried before the 1.65 was selected). It has several poor lines and hyphenates several words, but it has no real disasters.
TeXbook References: 96, 107. Also: 96, 107, 272, 317, 348, 364, 394, 451.

Related Primitives: tolerance, emergencystretch, badness.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

prevdepth Box
Internal Quantity
Synopsis: \prevdepth

Description:

    NORMALLY, \prevdepth holds the depth of the box most recently added to the current vertical list [79]. TeX uses that value to put interline glue between boxes on the list. The special value -1000pt suppresses the next interline glue, and it is placed at the beginning of most new vertical lists. The Plain TeX macro \nointerlineskip is just `\prevdepth=-1000pt' [80]. However, vertical lists begun by \halign and \noalign do not begin with -1000pt. Each keeps the interline glue used by the list which contains it. Finally, \prevdepth is not affected by \unvbox or \unvcopy [282].
Example:

  1. \setbox0=\hbox{Box 0. Every}
  2. \setbox1=\hbox{Box 1. jogger}
  3. \setbox2=\hbox{Box 2. runs}
  4. \setbox3=\hbox{Box 3. in}
  5. \setbox4=\hbox{Box 4. place.}
  6. \vtop{
  7. \global\dimen0=\the\prevdepth\copy0
  8. \global\dimen1=\the\prevdepth\copy1
  9. \global\dimen2=\the\prevdepth\copy2
 10. \global\dimen3=\the\prevdepth\copy3
 11. \global\dimen4=\the\prevdepth\copy4
 12. \global\dimen5=\the\prevdepth
 13. }
 14. \vskip0.5\baselineskip
 15. \halign
 16. {&\quad#\hfil\cr
 17. \bf Box&\bf Depth&\bf Prevdepth\cr
 18. 0&\the \dp0& \the\dimen0\cr
 19. 1&\the \dp1& \the\dimen1\cr
 20. 2&\the \dp2& \the\dimen2\cr
 21. 3&\the \dp3& \the\dimen3\cr
 22. 4&\the \dp4& \the\dimen4\cr
 23. End&& \the\dimen5\cr
 24. }
Produces: See typeset version.

Comments:

  • The \vtop constructed in lines 6-13 contains the 5 boxes from lines 1-5. Just before each \hbox is added to the \vtop, \prevdepth is stored in a \dimen register.
  • The \halign constructed in lines 15-24 displays the number, depth, and \prevdepth for each box.
TeXbook References: 79-80. Also: 79-80, 89, 271, 281, 282.

Related Primitives: baselineskip, unvbox, unvcopy.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

prevgraf Paragraph
Internal Quantity
Synopsis: \prevgraf

Description:

    THIS quantity holds the number of lines in the last completed paragraph. TeX uses \prevgraf in its line-breaking routine only with hanging indentation and a nonstandard \parshape [103]. TeX assumes each math display [188] and allignment display [190] is only three lines long. If either is longer, a manual adjustment to \prevgraf may be required [188].
Example:

  1. \def\ta#1{\the\prevgraf\prevgraf=#1}
  2. \hangafter=14\hangindent=3em\hsize=4.75in
  3. There are cries, sobs, confusion among the people, and at\ta{2} that
  4. moment the cardinal himself, the Grand Inquisitor, passes by\ta{4} the
  5. cathedral. He is an old man, almost ninety, tall\ta{6} and erect, with
  6. a withered face and sunken eyes, in\ta{8} which there is still a gleam
  7. of light. He is\ta{10} not dressed in his brilliant cardinal's robes,
  8. as he was\ta{12} the day before, when he was burning the enemies of
  9. the Roman Church~\char144\kern2em\hfill Fyodor Dostoyevsky, {\it The
 10. Brothers Karamazov}\the\prevgraf\par\the\prevgraf\par
Produces: See typeset version.

Comments:

  • The results of this example probably look confusing!
  • Line 2 tells TeX to begin hanging indentation on line 15 of the next paragraph.
  • Lines 3-10 hold the paragraph. When typeset, it is only seven lines long, and indentation begins on line 3.
  • Line 1 defines a macro \ta which typesets the current value of \prevgraf and assigns it a new value.
  • Lines 3-8 make six calls to \ta. The results of those calls show TeX does not change \prevgraf on a line-by-line basis in a paragraph. Rather, at the end of a paragraph, TeX takes the current value of \prevgraf, which is normally zero but is twelve in this example, and uses it to help determine line-breaks in the paragraph. So, after making two normal lines, TeX thinks it is on line 15 and begins hanging indentation. Finally, at the end of the paragraph, \prevgraf is 19.
TeXbook References: 103. Also: 103, 188, 190, 214, 271.

Related Primitives: hangafter, parshape.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

radical Math
Command
Synopsis: \radical<27-bit number><single character or {subformula}>

Description:

    SQUARE roots and other radicals are frequently used in certain branches of mathematics. When typeset, the radical has two parts: a symbol slightly taller than the following expression and a rule which begins at the top of the symbol and extends the width of the expression. Only the symbol is in the font. The rule is supplied by the typesetting program [nr]. The \radical command tells TeX to treat the following number as a \delimiter and to create a radical using it appropriate for the following character or subformula [157]. In actual practice the small and large symbols in the \delimiter are not sufficient for mathematical typesetting because they can't grow, and the subformula may have a large height. So, the tfm font files used with TeX contain lists of characters which have the same basic shape but different heights. TeX tries each character in a list until it finds one which will work with the material at hand. The CM math extension font can construct square roots of arbitrary height [nr]. The layout of tfm files is precisely described in METAFONT: The Program [* 1087-1096]. In particular * 1094 explains how lists of characters are built.
Example:

  1. \def\sqrt{\radical"0270370 }% page 360 of TB does not have the class digit.
  2. $\mathchar"270\; \mathchar"371 \;
  3.  \mathchar"372\; \mathchar"373 \;
  4.  \mathchar"374   \mathchar"375$
Produces: See typeset version.

Comments:

  • Line 1 shows the Plain TeX definition of \sqrt.
  • Line 2 shows the small and large characters for \delimiter"0270370.
  • Line 3 shows two other symbols appropriate for taller material.
  • Finally, line 4 shows the symbol which is used with the following vertical bar to construct arbitrarly tall square roots.
TeXbook References: 157, 291. Also: 157-159, 291, 443.

Related Primitives: delimiter.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

raise Kern
Command
Synopsis: \raise<dimen><box>

Description:

    THIS command raises (or lowers with a negative <dimen>) a box on the current list. It may only be used in horizontal mode [285] or math mode [290].
Example:

  1. \def\ttr#1%
  2. {%
  3.      \setbox0=\hbox{{\selffamily AD [}}%
  4.      \setbox1=\hbox{{\selffamily AD ]}}%
  5.      \raise0.45\dp0\box0%
  6.      {\selffamily AE  #1}%
  7.      \raise0.45\dp1\box1%
  8. }%
  9. Font AD is: {\selffamily AD \fontname\font}.\par
 10. Font AE is: {\selffamily AE \fontname\font}.\par
 11. The current font is: \fontname\font\ (10.0pt is implied).\par
 12. This requires horizontal mode \ttr{285}\ or math mode \ttr{290}.\par
 13. This requires horizontal mode [285] or math mode [290].
Produces: See typeset version.

Comments:

  • The \ttr macro is a simplified version of one macro these reference pages use to make a reference to a page in The Texbook. The working version does not require the control space on line 12.
  • The macro uses one point size for the brackets and a second for the page number. Lines 9-11 show each of the font point sizes.
  • The macro raises each bracket a slight amount (e.g., 0.45\dp0 on line 5).
  • I used trial and error to choose the point sizes and other numbers in \ttr.
  • Line 12 shows a sample line with two page references.
  • Line 13 shows the same text but with everything in the same font.
  • The \afterassignment reference page shows an updated version of how these pages make references.
TeXbook References: 285. Also: 66-67, 80, 151, 179, 193, 285, 290, 408.

Related Primitives: lower, moveleft, moveright.

For Additional Examples, see: afterassignment, mathchoice

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

read File I/O
Command
Synopsis: \read<number> to <control sequence>

Description:

    THIS command reads material from a file or from the terminal. Normally, TeX reads a single line for each \read. However, if the number of left and right braces on the line are different, TeX reads additional lines until the same number of braces are found. TeX reads from a file if the file associated with number is open and has unread material in it. Otherwise, TeX reads from the terminal. When TeX reads from the terminal, it displays the <control sequence> on the terminal as a prompt unless <number> is negative [217]. Expansion of tokens is suppressed when TeX is reading tokens for <control sequence> [215].
Example:

     \def\tfn{junk}
     \openin\traux=\tfn\relax
     \read\traux to \tts
     \closein\traux
     |\tts|\par
     \tts \tfn.
Produces: See typeset version.

Comments:

  • This gives a simple example of the three input commands: \openin, \read, and \closein.
  • Also, it shows the file name used with \openin can be placed in a control sequence.
TeXbook References: 217. Also: 215, 217, 276, 346, 401.

Related Primitives: openin, closein.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

relax Macro
Command
Synopsis: \relax

Description:

    ACCORDING to The TeXbook, ``TeX does nothing'' when it encounters \relax [279]. Actually, \relax may tell TeX, ``This is the end of what you've been doing'' [71]. Or, it may say, ``Be prepared, we're about to change course'' [353].
Example:

  1. \def\tmoveA{\hskip3pt}
  2. \def\tmoveB{\hskip3pt\relax}
  3. \def\tplus#1{There she blows, six points---or in printerspeak #1 plus 6pt
  4. ---off the starboard bow.\par}
  5. \tplus{\tmoveA}
  6. \tplus{\tmoveB}
  7. \def\getcountA#1{\the\count#1}
  8. \def\getcountB#1{\the\count#1\relax}
  9. \count3 = 10
 10. \count31=15
 11. \getcountA 3% count3 is of course 10.
 12. 1. Be sure to ... \the\count3\ and \the\count31\par
 13. \getcountB 3% count3 is of course 10.
 14. 1. Be sure to ... \the\count3\ and \the\count31\par
Produces: See typeset version.

Comments:

  • This example shows two ways the lack of a \relax can cause problems.
  • The first problem (lines 1-6) generally shows up as a run-time error, but the error message may be cryptic (TeX complaining about a ``missing number'' or an ``illegal unit of measure'').
  • The second problem (lines 7-14 can be more difficult to track down particularly if the real problem (`\count#1}' at the end of line 7) is buried deep in another macro. When TeX expands line 11, it makes \the\count 3, but there is nothing on line 7 to tell TeX that the register number it is building is done. So, TeX continues to the next line where it reads `1.'. The `.' stops the register number and \the\count 31 is typeset. Either a space or \relax at the end of line 7 will prevent the problem.
  • Although lines 8 and 13-14 fix the problem, they introduce a new problem. If it is fixed (add a \par or a \vskip between lines 13 and 14), then the original problem doesn't show up.
  • Even so, the second problem is worth examining. It took the author several enounters with it, before he learned to avoid it.
TeXbook References: 71, 279. Also: 23, 25, 71, 240, 276, 279, 307, 353.

For Additional Examples, see: / (italic correction), accent

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

relpenalty Math (Penalties)
500 * Parameter (integer)
Synopsis: \relpenalty

Description:

    JUST as TeX does not randomly hyphenate words, it does not randomly break math expressions between lines in a paragraph. TeX only considers a break after a relation (e.g., = or <) or a binary operation (e.g., + or ×) [173]. TeX inserts a penalty after a relation [174] which is not enclosed in braces and is not part of a generalized fraction [173]. The actual value of the penalty added after a relation in an expression is the value of \relpenalty at the end of the expression [101]. However, the penalty is not inserted if: a) the relation is the final item in the entire list; b) the value of the penalty is 10,000 or more; or c) the next item in the list is a penalty item [446-447].
TeXbook References: 174. Also: 101, 174, 272, 322, 348, 446.

Related Primitives: binoppenalty.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

right Math
Command
Synopsis: \right<delim>

Description:

    THIS command ends a construction which has a delimiter on either side of a subformula. TeX computes how large the delimiter should be based on what is in the subformula. There are three main rules for using \right: a) there must be a matching \left command; b) the `\left ... \right' pair must occur in the same group; and c) the resulting subformula must be typeset on 1 line. However, the delimiters need not match (e.g., `(...]' is fine). Also, if a `.' is used for either delimiter, it will be omitted. TeX makes the delimiter just big enough to cover the subformula. While that is what is needed most of the time, there are instances when TeX makes an outer delimiter that is too small [148-149]. Also, there are times when the `\left ... \right' pair puts more space around the subformula than one of Plain TeX's \big commands puts [171].
Example:

  1. \def\mkinvder#1.#2%
  2. {%
  3.      $$\displaylines% Plain TeX. It uses \halign{}. [194 & 362] in TTB
  4.        {%
  5.           \hbox to 0.25in{\hfil#1.\ \ }%
  6.           D_x^{-1}\left({#2}\right).\hfill\cr% In \halign so need \cr.
  7.        }%
  8.      $$%
  9. }
 10. In numbers 1--15 find the indicated inverse derivative.
 11. \mkinvder 1.{3x^2 + 2x + 1}
 12. \dots
 13. \mkinvder 15.{2x^2 + 7x + 3 \over x + 3}
Produces: See typeset version.

Comments:

  • This example shows the utility of the `\left ... \right' pair.
  • Lines 1-9 define a macro which formats an inverse derivative. Such a macro could be used to prepare problem sheets, exams, or exercises in a book. The use of \left and \right on line 6 instead of fixed height delimiters such as \bigl and \bigr mean the parenthesis grow as large as they need to be.
  • Lines 11 and 13 show how natural it is to send an expression to the macro.
  • Line 3 uses Plain TeX's \displaylines. It makes the numbers line up.
TeXbook References: 148-149. Also: 148-150, 155-157, 171, 196, 292, 437.

Related Primitives: left, delcode, delimiter.

For Additional Examples, see: delimiterfactor, nulldelimiterspace, vcenter

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

righthyphenmin Hyphenation
3 * Parameter (integer)
Synopsis: \righthyphenmin=<number>

Description:

    THIS parameter holds the minimum number of characters that must appear at the end of a hyphenated word (i.e., after the `-'). In particular, TeX will not hyphenate words with fewer than \lefthyphenmin + \righthyphenmin characters [454]. The whatsit\mkindex{whatsit`5`language} made by a change to \language includes the current value of \righthyphenmin [455]. Changes made to \righthyphenmin are local to the group containing the change [nr].
Example:

  1. \def\tstoryA{There are cries, sobs, confusion among the people, and at
  2. that moment the cardinal himself, the Grand Inquisitor, passes by the
  3. cathedral. He is an old man . . .}
  4. {\language255\hyphenation{mome-nt}}
  5. \count0=\righthyphenmin
  6. \setbox0=\vbox{\hsize=2.25in\language255 \tstoryA}
  7. \setbox1=\vbox{\hsize=2.25in\language255\righthyphenmin=2 \tstoryA}
  8. \hbox to \hsize{\box0\hfill\box1}
  9. The values are: \the\count0\ and \the\righthyphenmin.
Produces: See typeset version.

Comments:

  • This example adds a non-standard hyphenation of `moment' to language 255's execption dictionary.
  • Line 6 typesets \tstoryA using the default value of \righthyphenmin.
  • Line 7 typesets the same material with the same language but with a smaller value of \righthyphenmin.
  • Lines 5, 8, and 9 show the change made to \righthyphenmin on line 7 is local.
TeXbook References: 273, 454. Also: 273, 364, 454, 455.

Related Primitives: lefthyphenmin, language.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

rightskip Paragraph
0pt * Parameter (glue)
Synopsis: \rightskip=<glue>

Description:

    THIS parameter holds glue which TeX inserts on the right of every line in a paragraph [100]. The value used is the one current when the paragraph ends [101].
Example:

     {\leftskip=0pt
     \rightskip=0pt plus2pc
     \spaceskip=.5em
     \noindent
     \tstory\par}% The \adjdemerits reference page holds the definition of \tstory
     \vskip3pt
     {\leftskip=2pc plus 1fil
     \rightskip=\leftskip
     \spaceskip=.5em
     \noindent\tstory\par}
Produces: See typeset version.

Comments:

  • The first paragraph is set flush left and ragged right. It uses a constant interword space.
  • The second paragraph uses stretchable glue on the left and right in addition to the constant interword space. This results in centered lines of unequal width.
TeXbook References: 100-101. Also: 100-101, 274, 317, 356, 393, 421.

Related Primitives: leftskip, parindent, parfillskip.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

romannumeral Character
Command
Synopsis: \romannumeral<number>

Description:

    THIS command converts a number to lowercase roman numerals [41]. The expansion is empty if the number is zero or negative [213]. It produces characters which have category code 12 (other) or 10 (space) [214].
Example:

  1. \romannumeral -1 \
  2. \romannumeral 0 \
  3. \romannumeral 1 \
  4. \romannumeral 5 \
  5. \romannumeral 10 \
  6. \romannumeral 50 \
  7. \romannumeral 100 \
  8. \romannumeral 500 \
  9. \romannumeral 1000 \par
 10. \number\year\ is \romannumeral\year\par
 11. \number\year\ is also \uppercase\expandafter{\romannumeral\year}\par
Produces: See typeset version.

Comments:

  • Lines 1-9 show \romannumeral works as expected with the key numbers.
  • Lines 10-11 show how to convert the current year into lowercase and uppercase roman numerals.
TeXbook References: 40-41. Also: 40-41, 213, 214, 252.

Related Primitives: number, lowercase.

For Additional Examples, see: expandafter, uccode

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

scriptfont Math (Fonts)
Internal Quantity
Synopsis: \scriptfont<4-bit family number>=<font identifier>

Description:

    WHEN TeX is in math mode, it typsets material using one of 16 families of fonts. Each family has three fonts: text, script, and scriptscript. The text, script, and scriptscript styles use the corresponding font. The \scriptfont command identifies a control sequence (obtained using the \font command) with the script font of a particular family. The command generates an error if the family number is not in the range 0-15. Any font may be placed in any family with the restriction that fonts in families 2 and 3 are required to have extra special parameters [153]. Math glue is defined using mu units. There are 18 mu in one em, and in script style, the em is taken from \scriptfont2 (the math symbols family) [168].
Example:

  1. \def\tmathfont#1#2#3#4#5#6#7%
  2. {%
  3.   \begingroup
  4.      \textfont0=#2
  5.      \textfont1=#3
  6.      \scriptfont0=#4
  7.      \scriptfont1=#5
  8.      \scriptscriptfont0=#6
  9.      \scriptscriptfont1=#7
 10.      \hsize=2in
 11.      \global\setbox#1=\vbox
 12.      {%
 13.           $$f(x) = \sum_{n=1}^\infty x^{n^{2}}\quad 0 < x < 1.$$
 14.      }%
 15.   \endgroup
 16. }
 17. \tmathfont{0}{\tenrm}{\teni}{\tenrm}{\teni}{\tenrm}{\teni}
 18. \tmathfont{1}{\tenrm}{\teni}{\sevenrm}{\seveni}{\fiverm}{\fivei}
 19. \hbox to 4.5in{\quad\box0\hfill\box1}
Produces: See typeset version.

Comments:

  • This example uses the macro defined on lines 1-16 to typeset the same expression twice.
  • Line 17 uses the same fonts for the text, script and scriptscript fonts. The result looks like it was made on a typewriter.
  • Line 18 uses the conventions of Plain TeX.
TeXbook References: 153. Also: 153, 168, 213, 271, 321, 351, 414-415, 441-442.

Related Primitives: textfont, scriptscriptfont, font, fam, scriptstyle.

For Additional Examples, see: mathchar, scriptscriptfont

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

scriptscriptfont Math (Fonts)
Internal Quantity
Synopsis: \scriptscriptfont<4-bit family number>=<font identifier>

Description:

    WHEN TeX is in math mode, it typsets material using one of 16 families of fonts. Each family has three fonts: text, script, and scriptscript. The text, script, and scriptscript styles use the corresponding font. The \scriptscriptfont command identifies a control sequence (obtained using the \font command) with the scriptscript font of a particular family. The command generates an error if the family number is not in the range 0-15. Any font may be placed in any family with the restriction that fonts in families 2 and 3 are required to have extra special parameters [153]. Math glue is defined using mu units. There are 18 mu in one em, and in scriptscript style, the em is taken from \scriptscriptfont2 (the math symbols family) [168].
TeXbook References: 153. Also: 153, 168, 213, 271, 351, 414-415, 441-442.

Related Primitives: textfont, scriptfont, font, fam, scriptscriptstyle.

For Additional Examples, see: mathchar

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

scriptscriptstyle Math
Command
Synopsis: \scriptscriptstyle

Description:

    THIS command is used to specify scriptscript style. TeX uses four main styles to typeset formulas and subformulas: display, text, script, and scriptscript. Each main style has a corresponding cramped style. The eight styles are referred to as: D, D', T, T', S, S', SS, and SS' where the primed letter means the cramped style. TeX uses the scriptscript font (\scriptscriptfont) for the current family (\fam) when it typesets material in scriptscript style (both regular and cramped) [140]. The body of the following table lists the style of the major components in a formula whose basic style is known:
    component in formula | current style of formula
 | D | D' | T | T' | S, SS | S', SS'
superscript | S | S' | S | S' | SS | SS'
subscript | S' | S' | S' | S' | SS' | SS'
numerator | T | T' | S | S' | SS | SS'
denominator | T' | T' | S' | S' | SS' | SS'
    Finally, \underline does not change style, but \overline, \sqrt, and math accents change regular styles to cramped ones [141].
Example:

  1. \setbox0 = \vbox{\hsize=1.5in
  2. $$\sum_{0\le i\le m \atop 0 < j < n}P(i,j)$$}
  3. \setbox1 = \vbox{\hsize=1.5in
  4. $$\sum_{\scriptstyle0\le i\le m \atop\scriptstyle 0 < j < n}P(i,j)$$}
  5. \hbox to 3.5in{\qquad\box0\hfill\box1}
Produces: See typeset version.

Comments:

  • This example shows an instance where TeX 's style rules don't work well [145].
  • Lines 1-2 use \atop to prepare a pair of double limits for a summation. TeX uses scriptscript style, and each line looks too small.
  • Lines 3-4 explicitly tell TeX to use scriptstyle for each part of the \atop construction. The resulting formula looks much better.
TeXbook References: 140-141. Also: 140-142, 145, 179, 292.

Related Primitives: displaystyle, textstyle, scriptstyle, scriptscriptfont, fam.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

scriptspace Math (Kern)
0.5pt * Parameter (dimen)
Synopsis: \scriptspace<dimen>

Description:

    BEFORE TeX adds the box holding a superscript or a subscript to a math list, it increases the width of the box by \scriptspace [445, 446].
Example:

  1. \def\tfn#1#2%
  2. {{%
  3.      \everymath{\scriptspace=#2}
  4.      #1.\quad
  5.      $ x^2_i = x_i * x_i$ and $ x^2 = x * x $.
  6. }}
  7. \tfn1{0pt}\par
  8. \tfn2{0.5pt}\par
  9. \tfn3{1pt}\par
 10. \tfn4{5pt}\par
 11. \tfn5{10pt}\par% extra space was added AFTER each sub or super script.
Produces: See typeset version.

Comments:

  • This example uses the macro defined on lines 1-6 to typeset two expressions using various values for \scriptspace. The extra level of grouping provided by the braces on lines 2 and 6 keep the change made to \everymath local to \tfn.
TeXbook References: 445-446. Also: 274, 348, 445-446.

Related Primitives: scriptstyle.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

scriptstyle Math
Command
Synopsis: \scriptstyle

Description:

    THIS command is used to specify script style. TeX uses four main styles to typeset formulas and subformulas: display, text, script, and scriptscript. Each main style has a corresponding cramped style. The eight styles are referred to as: D, D', T, T', S, S', SS, and SS' where the primed letter means the cramped style. TeX uses the script font (\scriptfont) for the current family (\fam) when it typesets material in script style (both regular and cramped) [140]. The body of the following table lists the style of the major components in a formula whose basic style is known:
    component in formula | current style of formula
 | D | D' | T | T' | S, SS | S', SS'
superscript | S | S' | S | S' | SS | SS'
subscript | S' | S' | S' | S' | SS' | SS'
numerator | T | T' | S | S' | SS | SS'
denominator | T' | T' | S' | S' | SS' | SS'
    Finally, \underline does not change style, but \overline, \sqrt, and math accents change regular styles to cramped ones [141].
Example:

  1. \def\mkcstyle#1#2% make cramped text in denominator of fake fraction
  2. {%
  3.      \vbox to 0pt
  4.      {%
  5.           \vss
  6.           \hbox{$#1{\atop #2^2}$}% The numerator is empty!
  7.           \kern0pt
  8.      }%
  9. }
 10. \halign{#\hfil&&\quad#\hfil\cr
 11. \it D&\it T&\it D\ftB, T\ftB&\it S&\it S\ftB&\it SS&\it SS\ftB\cr
 12. \noalign{\vskip2pt\hrule\vskip3pt}
 13. $\displaystyle x^2$&$x^2$&\mkcstyle{\displaystyle}{x}&% D  T  D',T'
 14. $\scriptstyle x^2$&\mkcstyle{\textstyle}{x}&%           S  S'
 15. $\scriptscriptstyle x^2$&\mkcstyle{\scriptstyle}{x}\cr% SS SS'
 16. $\displaystyle X^2$&$X^2$&\mkcstyle{\displaystyle}{X}&
 17. $\scriptstyle X^2$&\mkcstyle{\textstyle}{X}&
 18. $\scriptscriptstyle X^2$&\mkcstyle{\scriptstyle}{X}\cr}
Produces: See typeset version.

Comments:

  • This example makes a table showing each of the styles. The table only has seven columns because cramped display style is the same as cramped text style.
  • Lines 1-9 define a macro which is used to coerce an expression into one of the cramped styles. The macro is a variation of ideas on page 141 of the actual tex file for The TeXbook.
  • The use of \textstyle on lines 14 and 17 may appear wrong, but the table in the Description section shows that \scriptstyle makes a denominator in cramped scriptscript style (which is not what we want). \textstyle makes a denominator in cramped script style.
  • The height of the superscript is different in each column. This is particularly apparent on the second line which uses an uppercase `X'.
TeXbook References: 140-141. Also: 140-142, 145, 179, 292.

Related Primitives: displaystyle, textstyle, scriptscriptstyle, scriptfont, fam.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

scrollmode Debugging
Command
Synopsis: \scrollmode

Description:

    NORMALLY, when TeX discovers an error in a file, it stops processing, displays a message on the terminal, and waits for instructions for what to do next. One option at this point is to press S (scroll future error messages). That tells TeX to continue processing without stopping if further syntax errors arise. However, TeX continues to stop for non-syntax errors (e.g., if a file is missing on an \input statement). Also, TeX continues to write normal error messages to the terminal [31]. If TeX encounters \scrollmode in a file, then it begins to process the file just as if S was entered in response to an error. This is a global change which continues until the end of the file or until one of the other `..mode' commands is encountered [32].
Example:

  1. \scrollmode
  2.   .
  3.   .
  4.   .
  5. \errorstopmode
Produces: See typeset version.

Comments:

  • If TeX encounters errors on lines 2-4, it writes an error message to the log file and displays a message on the terminal, but it won't stop for user input except for errors such as a missing file on an \input statement.
  • After line 5 TeX resumes normal error processing.
TeXbook References: 32. Also: 32, 277.

Related Primitives: batchmode, errorstopmode, nonstopmode.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

setbox Box
Command
Synopsis: \setbox<8-bit register number>=<hbox or vbox>

Description:

    THE \setbox command puts material in a box register (\box0 to \box255). Box registers are local to a group. A box register is either void or it contains an \hbox, \vbox, or \vtop. Once material is placed in a box, it may be typeset or moved by \box, \copy, \vsplit, or one of the unbox commands [120].
Example:

  1. \setbox0=\hbox{Box 0, level 1.}
  2. \setbox1=\hbox{Box 1, level 1.}
  3. \bgroup
  4.      \setbox0=\hbox{Box 0, level 2.}
  5.      \setbox1=\hbox{Box 1, level 2.}
  6.      \bgroup
  7.           \setbox0=\hbox{Box 0, level 3.}
  8.           \global\setbox1=\hbox{Box 1, level 3, global.}
  9.           \bgroup
 10.                \setbox0=\hbox{Box 0, level 4.}
 11.                \setbox1=\hbox{Box 1, level 4.}
 12.                \unhbox0\quad\unhbox1\par
 13.           \egroup
 14.           \unhbox0\quad\unhbox1\par%\box1 is now empty in all levels!
 15.      \egroup
 16.      \unhbox0\quad\unhbox1\par
 17. \egroup
 18. \unhbox0\quad\unhbox1\par
Produces: See typeset version.

Comments:

  • Lines 3, 6, and 9 begin groups. Each group puts material in \box0 and \box1. Then, the group unboxes the two boxes just before it ends.
  • The contents of \box0 are kept straight by this grouping.
  • But \box1 is made global on line 8. That means the level 1 and level 2 versions of \box1 are replaced by the level 3 version. Thus, when the level 3 version is unboxed in line 14, the boxes for the remaining levels become void.
TeXbook References: 120. Also: 66-67, 77, 81, 120, 276, 279, 286, 291, 386-392.

Related Primitives: box, hbox, vbox, vtop, vsplit, unhbox, unhcopy, unvbox, unvcopy.

For Additional Examples, see: accent, cleaders

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

setlanguage Hyphenation
Command
Synopsis: \setlanguage<number>

Description:

    THIS command is used in restricted horizontal mode to work with several different languages. It changes the current language and makes the language whatsit\mkindex{whatsit`5`language}, but it does not change \language. If <number> is negative or greater than 255, zero is used [455].
Example:

  1. {\language254\hyphenation{am-ong}}
  2. {\language255\hyphenation{I-nquisitor mome-nt}}
  3. \def\tlangA{\lefthyphenmin=2\righthyphenmin=1\setlanguage254}
  4. \def\tlangB{\lefthyphenmin=1\righthyphenmin=1\setlanguage255}
  5. \def\tstoryA{\language254 There are cries, sobs, confusion among the
  6. people, and at that moment the cardinal himself, the Grand Inquisitor,
  7. passes by the cathedral. He is an old man . . .}
  8. \def\tstoryB{\setbox2=\hbox{\tlangA There are cries, sobs, confusion
  9. among the people, and at that \tlangB moment the cardinal himself, the
 10. Grand Inquisitor, passes by the cathedral. He is an old man . . .}}
 11. \setbox0=\vbox{\hsize=2.25in \tstoryA}
 12. \setbox1=\vbox{\hsize=2.25in\language255 \tstoryB\unhbox2}% First, make box2
 13. \hbox to \hsize{\box0\hfill\box1}%                          then,  unbox it.
Produces: See typeset version.

Comments:

  • This example should be compared to the one on the \language reference page.
  • Here, \tstoryB is made in a box (i.e., in restricted horizontal mode). The language switching on lines 8-9 uses \setlanguage (see lines 3-4).
TeXbook References: 455. Also: 287, 455.

Related Primitives: language, lefthyphenmin, righthyphenmin.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

sfcode Character
Internal Quantity
Synopsis: \sfcode<8-bit number>

Description:

    EACH character in a font has a space factor code that is an integer between 0 and 32767. The code is used to adjust the space factor in a horizontal list. The uppercase letters A-Z have space factor code 999. Most other characters have code 1000 [76]. However, Plain TeX makes `)', `'', and `]' have space factor code 0. Also, the \frenchspacing and \nonfrenchspacing modes in Plain TeX work by changing the \sfcode for: `.', `?', `!', `:', `;', and `,' [351].
Example:

     \def\junkspacing{\sfcode`\.32767 \sfcode`\?6000 \sfcode`\!3000
       \sfcode`\:2500 \sfcode`\;2000 \sfcode`\,1500}
     \def\nonfrenchspacing{\sfcode`\.3000 \sfcode`\?3000 \sfcode`\!3000
       \sfcode`\:2000 \sfcode`\;1500 \sfcode`\,1250}
     \def\frenchspacing{\sfcode`\.1000 \sfcode`\?1000 \sfcode`\!1000
       \sfcode`\:1000 \sfcode`\;1000 \sfcode`\,1000}
     % Quotes are intentionally omitted in the following story:
     \def\tstoryC{Once upon a time, there was a naughty squirrel. Where shall I eat
      today? it asked. There were three options: a distant oak tree; a nearby
     walnut tree; and a freshly-stocked bird feeder. I think }
     %
     \parindent 1.5pc
     \junkspacing \tstoryC\par
     \nonfrenchspacing \tstoryC\par
     \frenchspacing \tstoryC\par
Produces: See typeset version.

Comments:

  • It takes a sharp eye (or careful measurement) to see the difference between the paragraphs set using french and nonfrench spacing. However, each is clearly different from the paragraph set using junkspacing.
  • The TeXBook uses \nonfrenchspacing, and these pages use \frenchspacing.
TeXbook References: 76. Also: 76, 214, 271, 286, 321, 345, 351.

Related Primitives: catcode, lccode, uccode, spacefactor.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

shipout File I/O
Command
Synopsis: \shipout<box>

Description:

    THIS command writes <box> to the dvi file. Normally, the command appears in the output routine, and the <box> is \box255, but the command may be used at any time with any box. TeX writes the non-zero values of \count0 through \count9 to the log file and the terminal when it ships out a box [254]. After every \shipout, TeX sets \deadcycles to zero [255]. If \tracingstats is 2 or larger, TeX writes memory usage statistics to the log file each time it does a \shipout [300].
TeXbook References: 253-255. Also: 227, 253-255, 279, 300, 302.

Related Primitives: output, deadcycles, tracingstats.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

show Debugging
Command
Synopsis: \show<token>

Description:

    THIS command displays the current meaning of <token> on the terminal and writes the meaning to the log file [10]. The command may be entered at the keyboard when TeX is waiting for input [299]. But, if it appears in a file, TeX interrupts processing of the file and waits for further instructions [nr].
Example:

  1. \def\tbox#1{\boxit{\hbox{#1}}}
  2. \def\tfn#1{\everymath{\nulldelimiterspace=#1}$y = {1\over2}x^2$\quad}
  3. \show\tbox
  4. \show\tfn
  5. \show The big Box.
  6. \setbox0=\tbox A
  7. \show\wd0
  8. \show\show
Produces: See typeset version.

Comments:

  • Lines 1 and 2 define macros which are shown by lines 3 and 4. The results appear on lines 9-11 and 12-14.
  • Line 5 and its results on lines 15-17 make it clear that \show only looks at the token immediately after the command.
  • The results for lines 7-8 (particularly lines 18 and 21) make it clear that \show doesn't show much for primitives.
TeXbook References: 10. Also: 10, 213, 215, 279, 299.

Related Primitives: meaning, showbox, showlists, showthe.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

showbox Debugging
Command
Synopsis: \showbox<8-bit number>

Description:

    THIS command writes the contents of a box register to the log file [66]. If \tracingonline is positive, it also displays the contents on the terminal [121]. By default at most 3 levels and 5 items per level are written. The parameters \showboxdepth and \showboxbreadth control the number of levels and items per level that are written [302].
Example:

  1. \setbox0=\boxit{\hbox{A}}%
  2. \setbox1=\hbox{B}%
  3. \setbox2=\hbox{\boxit{\copy0}\kern25pt\boxit{\copy1}}%
  4. \setbox3=\boxit{\box2}
  5. \showboxdepth=100
  6. \showboxbreadth=100
  7. \showbox3
  8. \box3
Produces: See typeset version.

Comments:

  • The box made by lines 1-4 does not appear complicated. It holds the letters `A' and `B' and several boxes around the letters. Yet it takes TeX over 50 lines to describe the construction.
  • The values on lines 5 and 6 are large enough to ensure that the \showbox command on line 7 will display the entire box.
  • Each of the dimensions in lines 9-59 is in points.
  • The *'s on line 58 mean the rule extends the height and depth of its box (which begins on line 15). Also, the * on line 59 means the rule extends the width of its box (which begins on line 12). The other rules work similarly.
TeXbook References: 66-67. Also: 66-67, 121, 234, 279.

Related Primitives: showboxbreadth, showboxdepth, showlists, show, showthe.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

showboxbreadth Debugging
5 * Parameter (integer)
Synopsis: \showboxbreadth=<number>

Description:

    THIS parameter determines how many items per level the \showbox and \showlists commands write to the log file [302].
Example:

  1. \setbox0=\boxit{\hbox{A}}%
  2. \setbox1=\hbox{B}%
  3. \setbox2=\hbox{\boxit{\copy0}\kern25pt\boxit{\copy1}}%
  4. \setbox3=\boxit{\box2}
  5. \showboxdepth=100
  6. \showboxbreadth=2
  7. \showbox3
  8. \box3
Produces: See typeset version.

Comments:

  • This example is identical to the one on the \showbox reference page except here the value assigned to \showboxbreadth on line 6 is 2 instead of 100.
  • The smaller value tells TeX to display no more than 2 items for a particular level.
  • The `etc.' on lines 15 and 16 means there are additional level 1 and level 2 items.
TeXbook References: 302. Also: 273, 302, 303, 348.

Related Primitives: showboxdepth, showbox, showlists.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

showboxdepth Debugging
3 * Parameter (integer)
Synopsis: \showboxdepth=<number>

Description:

    THIS parameter determines how many levels the \showbox and \showlists commands write to the log file [302].
Example:

  1. \setbox0=\boxit{\hbox{A}}%
  2. \setbox1=\hbox{B}%
  3. \setbox2=\hbox{\boxit{\copy0}\kern25pt\boxit{\copy1}}%
  4. \setbox3=\boxit{\box2}
  5. \showboxdepth=2
  6. \showboxbreadth=100
  7. \showbox3
  8. \box3
Produces: See typeset version.

Comments:

  • This example is identical to the one on the \showbox reference page except here the value assigned to \showboxdepth on line 5 is 2 instead of 100.
  • The smaller value tells TeX to display no more than 2 levels.
  • The `[]' at the end of line 15 means the \vbox on line 15 contains material which is not shown.
TeXbook References: 302. Also: 79, 273, 302, 303, 348.

Related Primitives: showboxbreadth, showbox, showlists.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

showlists Debugging
Command
Synopsis: \showlists

Description:

    THIS command writes to the log file the lists that are being worked on in the current mode and in all enclosing modes where work has been suspended [88]. If the command is placed in the output routine, then the current page and recent contributions are written [112]. If \tracingonline is set to a positive number, the results are also displayed on the terminal [303]. Finally, \showboxbreadth and \showboxdepth work as they do with \showbox to limit the amount of material that is displayed [302].
Example:

  1. Hello {\it World}. {\selffamily AB Now} . . .
  2. \showboxdepth=100
  3. \showboxbreadth=100
  4. \setbox0=\hbox{\boxit{\hbox{\selffamily AA A}}\showlists}%
  5. \box0
Produces: See typeset version.

Comments:

  • The \showlists command on line 4 writes three lists to the log file. Lines 2 and 3 assign large values to \showboxdepth and \showboxbreadth. They insure that none of the lists are abbreviated.
  • The first list is in restricted horizontal mode and is the result of \setbox on line 4. The list consists of lines 6-20. With the exception of lines 6 and 20, the output looks the same as what \showbox makes.
  • The second list consists of lines 21-47. Many of the lines look like line 23 which holds TeX's internal name for the current font and a character in that font. Line 30 shows a kern for `Wo'. The \fontdimen reference page explains the values on line 28 which holds glue placed between words.
  • The final list consists of lines 48-49. It is the vertical list which holds the example and is empty.
TeXbook References: 88-89, 158-159. Also: 88-89, 95, 112, 125, 158-159, 279, 293.

Related Primitives: showboxbreadth, showboxdepth, showbox, show, showthe.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

showthe Debugging
Command
Synopsis: \showthe<internal quantity>

Description:

    THIS command gets the value of an internal quantity. The result is displayed on the terminal and written to the log file [121]. The TeXbook only defines <internal quantity> in an answer to an exercise [279 and 336]. Basically, it is one of the internal quantities [271] or parameters [272-275].
Example:

  1. \setbox0=\hbox{A}
  2. \showthe\wd0 %      these are internal quantities---page 271 of TTB.
  3. \showthe\ht0
  4. \showthe\dp0
  5. \showthe\tolerance %   this is parameter: integer---page 272
  6. \showthe\hsize %       this is parameter: dimen-----page 274
  7. \showthe\parfillskip % this is parameter: glue------page 274
  8. \showthe\medmuskip %   this is parameter: muglue----page 274
Produces: See typeset version.

Comments:

  • This example uses \showthe to write the value of the items on lines 2-8 to the log file. The comments indicate the type of each item.
  • TeX makes two lines of output for each of these. The first line begins with a `>' and continues with a value (e.g., the odd lines 9-21). The second line begins with `l.' and shows the line number in the file and the command which made the preceeding value (e.g., the even lines 10-22).
TeXbook References: 279 . Also: 121, 215, 279.

Related Primitives: show, showbox, showlists.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

skewchar Math (Character)
Internal Quantity
Synopsis: \skewchar<font>=<-1 or 8-bit number>

Description:

    THIS quantity is one of two primitives that (in my opinion) The TeXbook does not adequately document. The following represents my current understanding of what \skewchar does based on page 443 of The TeXbook, section 741 of TeX : The Program, pages 42-44 of Computer Modern Typefaces, and experimentation. Two CM fonts have working \skewchar values: the math italic font and the math symbol font [430-431]. Neither font contains accents. But, both fonts contain characters with which it would be nice to use accents, and those characters are in italics. That means an accent that is just centered above a character will be in the wrong position. The accent needs to be shifted to make everything look right. TeX does this by: a) selecting a character in each font that does not need accents (that character becomes the font's skew char); b) specifying a ligature between the font's skew char and every other character in the font which requires an accent adjustment (pages 42-44 of CMT contain these ligatures); c) using the appropriate kern from the ligature between a character and the shew char when it positions an accent over the character. When TeX loads a new font, it sets the \skewchar of the font to \defaultskewchar [273]. If the \skewchar is not in the range 0-255, TeX does not make the adjustments described above. In particular a \skewchar value of -1 disables the adjustments.
Example:

  1. The skew char for the math italic font is: $\mathchar"17F$.\par
  2. The skew char for the math symbol font is: $\mathchar"230$.\par
  3. \def\tma#1#2%
  4. {%
  5.      \skewchar\teni=-1
  6.      \skewchar\tensy=-1
  7.      $ #1 $ vs $\mathaccent"14 #1$ vs
  8.      \skewchar\teni="7F
  9.      \skewchar\tensy="30
 10.      $ \mathaccent"14 #1$. Adjusted $#2*0.5mu$ units.\par
 11. }
 12. \tma{\mathchar"141}5
 13. \tma{\mathchar"241}7
 14. \tma{\mathchar"254}1
Produces: See typeset version.

Comments:

  • Lines 1-2 typeset the skew char of two CM fonts.
  • Lines 3-11 define a macro which typesets a character three times: without an accent, with an accent with a null skew char, and with an accent with a working skew char. Also, the macro typesets the number of math units the accent is moved for the character.
  • Lines 12-14 use \tma with three different math characters. The adjustment values are from CMT.
TeXbook References: 443. Also: 214, 271, 273, 277, 351, 414, 430-431, 443.

Related Primitives: defaultskewchar, mathaccent.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

skip Registers
Internal Quantity
Synopsis: \skip<8-bit register number>=<glue>

Description:

    THERE are 256 skip registers: \skip0 to \skip255. Each may hold <glue>. The commands \advance, \multiply, and \divide allow limited arithemetic with the registers. A skip register may be placed in a dimen register. TeX converts glue to a dimension by dropping the stretch and shrink components of the glue [118]. The skip registers obey TeX's grouping structure. So, changes to a register inside a group will not affect the value of the register outside the group unless \global is used with the register [119]. The command `\showthe\skip n' writes the value for \skip n to the terminal and to the log file [121]. The register \skip255 is available for temporary storage [122].
Example:

  1. \skip1=0.75\baselineskip plus 10pt minus 6pt
  2. \skip2=1.5\skip1
  3. \skip3=-\skip2
  4. \skip4=0.66667\skip3
  5. The skips are: \the\skip1; \the\skip2; \the\skip3; \the\skip4.\par
  6. \skip5=6pt plus-4pt minus2pt
  7. \advance\skip5 by \skip1
  8. \skip6=\skip1
  9. Skip5 = \the\skip5; skip6 = \the\skip6.\par
 10. \dimen1=\skip1
 11. \count1=\dimen1
 12. \count4=\skip4
 13. Dimen1 = \the\dimen1; count1 = \the\count1; count4 = \the\count4.\par
Produces: See typeset version.

Comments:

  • Lines 1-4 show the stretch and shrink components of glue are lost when one \skip register is set equal to a fractional multiple of another register.
  • Lines 6-8 show that is not the case if two skip registers are added or used in a simple assignment.
  • Finally, Lines 10-12 show how \skip registers are converted to \dimen and \count registers.
TeXbook References: 118-122. Also: 118-122, 271, 276, 346-347, 349, 352, 363, 394.

Related Primitives: skipdef, advance, multiply, divide, dimen.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

skipdef Registers
Command
Synopsis: \skipdef<name>=<8-bit register number>

Description:

    A skip register may be used directly (e.g., `\skip25=3pt plus1pt minus1pt') [118] or indirectly in one of two ways. Each indirect way involves setting up a symbolic name for a register (e.g., \smallskip). The first indirect way uses the primitive \skipdef (e.g., `\skipdef\smallskip=25'); this makes \smallskip equivalent to \skip25. So, the command `\smallskip=3pt plus1pt minus1pt' sets up glue that might be used with \vskip [119]. The second indirect way uses the Plain TeX command \newskip (e.g., `\newskip\smallskip'). This time the control sequence \smallskip is a skip register, but it is not at all apparent which one (the log file should contain a line `\smallskip=\skip n' for some n) [121]. The direct method is fine for registers used locally in a macro or in a group. The \newskip method (or something equivalent if Plain TeX is not used) is the preferable indirect method. If macros from several sources are used, and two different \skipdef's use the same register number, the macros may interfere with each other. This type of problem is difficult to track down [nr]. TeX suppresses expansion when it is reading a control sequence that will be defined by a \skipdef [215].
Example:

     % skip variables from Plain TeX [349].
     \newskip\smallskipamount
     \newskip\medskipamount
     \newskip\bigskipamount
     \newskip\normalbaselineskip
     \newskip\normallineskip
     \smallskipamount=3pt plus 1pt minus 1pt
     \medskipamount=6pt plus 2pt minus 2pt
     \bigskipamount=12pt plus 4pt minus 4pt
     \normalbaselineskip=12pt
     \normallineskip=1pt
Produces: See typeset version.

TeXbook References: 119. Also: 119, 215, 277, 346-347.

Related Primitives: skip.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

spacefactor Paragraph
Internal Quantity
Synopsis: \spacefactor=<number>

Description:

    THERE are two ways to control interword spacing. The normal way uses \spacefactor; the alternate way uses \spaceskip and \xspaceskip. The normal way is used unless \spaceskip and/or \xspaceskip is nonzero. Each of the 256 characters in a font has a space factor code which is an integer from 0 to 32767. Initially, the uppercase letters `A' to `Z' are assigned 999 and all other characters are assigned 1000. TeX maintains \spacefactor, but its value f may be changed at any time. At the start of a new horizontal list it is set to 1000. Each time a character with a space factor code g is added to the current list, f is set to g unless: a) g is zero (f is not changed); or b) f < 1000 < g (f is set to 1000). Each font has a number of special <dimen> parameters (see \fontdimen). Four of them are used to determine interword glue: normal space, normal stretch, normal shrink, and extra space. When f is 1000, the interword glue is glue consisting of the three normal dimensions. Otherwise, the stretch component is multiplied by f/1000 and the shrink component is multiplied by 1000/f. Finally, if f >= 2000, the extra space dimension is added to the normal space component of the interword glue [76].
Example:

  1. {\sfcode`\.3000\sfcode`\?3000\sfcode`\!3000%
  2.  \sfcode`\:2000\sfcode`\;1500\sfcode`\,1250
  3. \tstory\par}% The \adjdemerits reference page holds the definition of \tstory
  4. \vskip6pt
  5. {\frenchspacing
  6. \tstory\par}% This book uses \frenchspacing.
Produces: See typeset version.

Comments:

  • Lines 1-2 use \sfcode values from Plain TeX's \nonfrenchspacing macro. The first paragraph has a small amount of extra space at the start of each sentence.
TeXbook References: 76. Also: 76, 271, 285, 363, 433.

Related Primitives: sfcode, spaceskip, xspaceskip, fontdimen.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

spaceskip Paragraph
0pt * Parameter (glue)
Synopsis: \spaceskip=<number>

Description:

    THERE are two ways to control interword spacing. The normal way uses \spacefactor f; the alternate way uses \spaceskip and \xspaceskip. If \xspaceskip is nonzero and f >= 2000, the \xspaceskip glue becomes the interword glue. Otherwise, if \spaceskip is nonzero, the \spaceskip glue has its stretch and shrink components multiplied by f/1000 and 1000/f, and that becomes the interword glue [76].
Example:

     \sfcode`\.3000\sfcode`\?3000\sfcode`\!3000%
      \sfcode`\:2000\sfcode`\;1500\sfcode`\,1250
     \xspaceskip=0pt
     \spaceskip=0.5em
     \tstory\par% The \adjdemerits reference page holds the definition of \tstory
Produces: See typeset version.

Comments:

  • This example makes every interword space exactly 0.5em. The result is a number of underfull boxes (short lines). Since \xspaceskip=0pt, no extra space is used between sentences.
  • A ragged right macro often uses \spaceskip and \xspaceskip.
TeXbook References: 76. Also: 76, 274, 317, 356, 429.

Related Primitives: xspaceskip, spacefactor.

For Additional Examples, see: rightskip

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

span Tables
Command
Synopsis: \span

Description:

    THIS command is used in an alignment, but it works differently depending on whether it is in the preamble or not. In the preamble it causes the next token to be expanded [238]. Outside the preamble it is used in place of the column separator `&'. The second use tells TeX to process the material on either side of the \span as normal, but to put it in one box instead of two boxes when the row of the table is actually typeset [243]. When \span appears outside the preamble in a \valign, rows get spanned instead of columns [249].
Example:

  1. %\newdimen\digitwidth % This appears in my formatting file.
  2. \setbox0=\hbox{0}
  3. \digitwidth=\wd0
  4. \catcode`?=13
  5. \def?{\kern\digitwidth}
  6. \def\er{\crcr\noalign{\hrule}}
  7. \def\tm{\hskip0.5em}
  8. \def\tfc#1{\tm\hfil\smash{\lower5pt\hbox{#1}}\hfil\tm}
  9. \def\strutA#1#2{\vrule height#1 depth#2 width0pt}
 10. \offinterlineskip
 11. \setbox0=\vbox{\halign
 12. {\strutA{9pt}{4pt}\vrule#&\tm#\hfil\tm&\vrule#&\tm\hfil#\hfil\tm&\vrule#&
 13. \tm\hfil#\hfil\tm&\vrule#&\tm\hfil#\hfil\tm&#\vrule\cr\er
 14. &\multispan7\hfil\bf Composition of Foods\hfil&\cr
 15. \omit\strutA{0.8pt}{0pt}\vrule&\multispan7\leaders\hrule height 0.8pt\hfill&\cr
 16. &&&\multispan5\hfil Percent by Weight\hfil&\cr
 17. \omit\strutA{0.4pt}{0pt}\vrule&&&\multispan5\leaders\hrule\hfill&\cr
 18. &\omit\hfil Food\hfil&&\omit\tfc{Protein}&&\omit\tfc{Fat}&&Carbo-&\cr
 19. &&&&&&&hydrate&\er
 20. &Apples&&    ??.4&&?.5&&13.0&\cr
 21. &Halibut&&   18.4&&5.2&&?...?&\cr
 22. &Lima Beans&&?7.5&&?.8&&22.0&\cr
 23. &Milk&&      ?3.3&&4.0&&?5.0&\cr
 24. &Mushrooms&& ?3.5&&?.4&&?6.0&\cr
 25. &Rye Bread&& ?9.0&&?.6&&52.7&\er
 26. }}
 27. \hbox to \pagewidthB{\hfil\box0\hfil\hfil}
Produces: See typeset version.

Comments:

  • This example should be compared to the one on the \halign reference page because it uses several tricks which were not needed by that example.
  • The first trick is line 15 which makes a thicker rule than normal after the first line of the header. The strut on line 12 makes the height and depth of each line in the table be 13 points. The \omit at the start of line 15 tells TeX to expect a custom template. It is a strut which is only 0.8 points tall and matches the height of the rule made later on the line.
  • The second trick occurs on line 17. It is similar to the first, only a smaller strut is made and the rule skips the the ``Food'' column.
  • The final trick occurs in two places: lines 1-5 where `?' is setup, and lines 20-25 where `?' helps align the decimal points in each column.
  • The table is from ``Tbl-A Program to Format Tables,'' by M. E. Lesk which in turn begins on page 157 of Unix Programmer's Manual, Volume 2, 1983.
TeXbook References: 238, 243-244. Also: 215, 238, 243-245, 248-249, 282, 330, 385.

Related Primitives: halign, omit, valign.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

special File I/O
Command
Synopsis: \special{<token list>}

Description:

    THIS command immediately expands the <token list> and places it in a whatsit\mkindex{whatsit}. When the page containing the whatsit is written by \shipout to the dvi file, the expanded material is written directly to that file [228]. The program which converts dvi output to printer or display output (e.g., dvips) should be able to use the extra material (e.g., to display an eps file or rotate text) or to ignore it [229].
Example:

  1. %\special{header=clock.ps}% this goes at beginning of main formatting file.
  2. \def\mkclockA#1#2% degrees to rotate: minute, hour hands.
  3. {%
  4.      \special{ps: gsave
  5.      currentpoint translate
  6.      1.0 -1.0 scale
  7.      #1 #2 clock
  8.      grestore}% clock.ps defines clock
  9. }
 10. The times are:\par
 11. \setbox0=\hbox to \hsize
 12. {%
 13.      \hfil
 14.      \mkclockA{0}{0}%
 15.      \kern 1in\mkclockA{-90}{-7}%
 16.      \kern 1in\mkclockA{-180}{-15}%
 17.      \kern 1in\mkclockA{-270}{-22}%
 18.      \kern 1in\mkclockA{-360}{-30}%
 19.      \hfil
 20. }
 21. \vbox to 1in{\vfil\box0\vfil}
Produces: See typeset version.

Comments:

  • The \special command is one of the few system dependent aspects of using TeX . I prepared these pages using a PostScript printer and dvips. Lines 1 and 4 show two different \special commands which work with my version of dvips.
  • Line 1 tells dvips, ``Here is a PostScript file which I want you to add to the PostScript file you are making.'' This line is commented out because a similar line appears in the main formatting file used to typeset these pages.
  • Line 4 tells dvips, ``Add the following PostScript commands to the file you are making.'' Each of the commands on lines 4-6 and 8 is a basic PostScript command, and line 7 calls clock which is defined in clock.ps. The clock routine requires two parameters: the number of degrees to rotate the minute and hour hands of the clock. Lines 7 and 15-18 show that TeX can customize the PostScript which appears in a \special.
  • This example is a simplified version of the routine which makes the clocks for these pages. That routine counts the number of clocks required; makes the first clock midnight; makes the last clock noon; and equalizes the elapsed time displayed by each of the other clocks. In particular, TeX keeps track of everything and makes all needed calculations.
TeXbook References: 228-229. Also: 216, 226, 228-229, 280.

Related Primitives: write.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

splitbotmark Inserts (Marks)
Command
Synopsis: \splitbotmark

Description:

    THIS command holds the mark text of the last mark in material split off by the most recent \vsplit command. It is null unless the material contains one or more marks. The value of \splitbotmark is global (i.e., it is not affected by grouping) [259].
TeXbook References: 259. Also: 213, 259, 280.

Related Primitives: mark, splitfirstmark, vsplit.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

splitfirstmark Inserts (Marks)
Command
Synopsis: \splitfirstmark

Description:

    THIS command holds the mark text of the first mark in material split off by the most recent \vsplit command. It is null unless the material contains one or more marks. The value of \splitfirstmark is global (i.e., it is not affected by grouping) [259].
Example:

  1. \def\tstoryB{There are cries, sobs, confusion among the people, and
  2. at that moment the cardinal himself, the Grand Inquisitor
  3. \mark{Grand Inquisitor}, passes by the cathedral. He is an old man,
  4. almost ninety, tall and erect, with a withered face and sunken eyes,
  5. in which there is still a gleam of light. He is not dressed in his
  6. brilliant cardinal's robes, as he was the day before, when he was
  7. burning the enemies of the Roman Church~\char144\kern2em\hfill Fyodor
  8. Dostoyevsky, {\it The Brothers Karamazov}}
  9. \splittopskip=15.2pt
 10. \def\strutA#1#2{\vrule height#1 depth#2 width0pt}
 11. \setbox1=\vbox{\hsize=2.5in\strutA{\splittopskip}{0pt}
 12.                \mark{Hello}\tstoryB\mark{World}}
 13. \dimen0=\ht1
 14. \advance\dimen0 by \dp1
 15. \advance\dimen0 by \splittopskip
 16. \divide\dimen0 by 2
 17. \setbox0=\vsplit1 to \dimen0
 18. \setbox2=\vbox to \dimen0{\unvbox0\vfill}
 19. \setbox3=\vbox to \dimen0{\unvbox1\vfill}
 20. \hrule
 21. \hbox to \hsize{\box2\hfil\box3}
 22. \hrule
 23. \strutA{\baselineskip}{0pt}\splitfirstmark, \splitbotmark.
Produces: See typeset version.

Comments:

  • Lines 11-12 make a box which holds three marks. Two of the marks are on line 12 and ultimately appear at the start and the end of the paragraph. The third is on line 3 and is in the body of the paragraph.
  • The \vsplit on line 17 moves the first two marks into \box0. As a result \splitfirstmark and \splitbotmark receive values.
  • The strut at the start of line 23 prevents the following line of text from touching the rule made by line 22.
TeXbook References: 259. Also: 213, 259, 280.

Related Primitives: mark, splitbotmark, vsplit.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

splitmaxdepth Inserts (Box)
4pt * Parameter (dimen)
Synopsis: \splitmaxdepth=

Description:

    THE operation \setbox100=\vsplit99 to 60pt uses the page-breaking routine with a page goal of 60 points to move material from \box99 to \box100. In the normal page-breaking routine the parameter \maxdepth controls the maximum depth of boxes placed on the page. The \splitmaxdepth parameter serves the same function in the page-breaking routine used with \vsplit [124]. The parameter \splitmaxdepth often appears in the <vertical mode material> used with \insert. Then, if the insertion needs to be split, \vsplit uses the last value of \splitmaxdepth in the material [281].
TeXbook References: 124. Also: 124, 274, 281, 348, 363, 417.

Related Primitives: vsplit, splittopskip, insert.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

splittopskip Inserts (Box)
10pt * Parameter (glue)
Synopsis: \splittopskip=<glue>

Description:

    AT the conclusion of a \vsplit operation, the box being split may be empty. If it is not, \splittopskip glue is placed at the top of the box. This is similar to the \topskip glue placed at the top of \box255 [124]. The parameter \splittopskip often appears in the <vertical mode material> used with \insert. Then, if the insertion needs to be split, \vsplit uses the last value of \splittopskip in the material [281].
Example:

  1. \splittopskip=18.3pt
  2. \def\strutA#1#2{\vrule height#1 depth#2 width0pt}
  3. \setbox1=\vbox{\hsize=2.5in\strutA{\splittopskip}{0pt}\tstory}
  4. \dimen0=\ht1 % The \adjdemerits reference page holds the definition of \tstory
  5. \advance\dimen0 by \dp1
  6. \advance\dimen0 by \splittopskip
  7. \divide\dimen0 by 2
  8. \setbox0=\vsplit1 to \dimen0
  9. \setbox2=\vbox to \dimen0{\unvbox0\vfill}
 10. \setbox3=\vbox to \dimen0{\unvbox1\vfill}
 11. \hrule
 12. \hbox to \hsize{\box2\hfil\box3}
 13. \hrule
Produces: See typeset version.

Comments:

  • This example contains pieces of a double column routine.
  • The value for \splittopskip on line 1 has no special significance, except it is different from \topskip.
  • Line 3 prepares a \vbox holding: a new \hsize; a strut which lowers the first line in the box; and the paragraph which will be split.
  • Lines 4-6 compute how much material is effectively in the box. Line 6 is necessary because after the \vsplit, \splittopskip space is added to \box1.
  • Line 8 splits the box, and lines 9-10 repackage the resulting two boxes.
  • The distance between the bottom of the first horizontal rule and the first baseline in each column is 18.3 points.
TeXbook References: 124. Also: 124, 274, 281, 348, 363, 397, 417.

Related Primitives: vsplit, splitmaxdepth, insert.

For Additional Examples, see: parshape

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

string Character
Command
Synopsis: \string<token>

Description:

    THIS command converts a single <token> into character tokens. If the token is a character or an active character, the result is the character. If the token is a control sequence, the result is \escapechar followed by the characters making up the name of the control sequence. TeX reads the token without expansion [213]. Each resulting character, including the \escapechar, receives category code 12 (other). Except, if a space occurs, it receives category code 10 [40]. The Plain TeX version of \newif uses \string and sets `\escapechar=-1' [348].
Example:

  1. \def\tstring#1{\string #1\par}
  2. \tstring{Hi~\TeX.}
  3. \tstring{~\TeX\ Hi.}
  4. \tstring{\TeX\ Hi~.}
  5. \string { Hi.\par% Where is the ending `}' ?
  6. % See how \string works with the 10 special characters.
  7. \string {
  8. \string }
  9. \string \
 10. \string ^
 11. \string &
 12. \string $
 13. \string #
 14. \string _
 15. \string ~
 16. \string %
 17. \TeX
 18. \%
Produces: See typeset version.

Comments:

  • Lines 2-4 illustrate \string followed by a character, an active character, and a control sequence.
  • Line 5 looks funny because the braces are not balanced, but it does not create an error.
  • Lines 7-16 show how \string works with TeX's 10 special characters. Each is printed except for the `%' on line 16 which acts as it normally does. That means the \string on line 16 is still waiting for a token. It finds one on line 17.
  • Finally, line 18 show one way to typeset a `%'.
TeXbook References: 40, 213. Also: 40-41, 213-215, 348, 377.

Related Primitives: escapechar.

For Additional Examples, see: escapechar

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

tabskip Tables
0pt * Parameter (glue)
Synopsis: \tabskip=<glue>

Description:

    THIS parameter holds glue which TeX places before the first column, after the last column, and between each column in an alignment [237-238]. Changes made to \tabskip inside a preamble are local to the alignment unless \globaldefs is positive. In particular, if \global preceeds \tabskip, TeX considers \global to be part of a template [238].
Example:

  1. \def\er{\crcr\noalign{\hrule}}
  2. \def\tg{0.22em plus 3em}
  3. \def\tm{\hskip\tg}
  4. \def\strutA#1#2{\vrule height#1 depth#2 width0pt}
  5. \def\mktable#1#2{\setbox#1=\vbox{\offinterlineskip
  6. \halign #2%
  7. {\vrule\strutA{10pt}{4pt}##\tabskip=\tg&##\hfil&##\vrule&##\hfil&% in a def
  8.  ##\vrule\tabskip=0pt&\tm\hfil##\hfil\tm&##\vrule\cr\er%           so use ##.
  9. &\multispan5\bf\hfil Major New York Bridges\hfil&\er
 10. &\omit\hfil Bridge\hfil&&\omit\hfil Designer\hfil&&Length&\er
 11. &Brooklyn&&          J. A. Roebling&& 1595&\cr
 12. &Manhattan&&         G. Lindenthal&&  1470&\cr
 13. &Williamsburg&&      L. L. Buck&&     1600&\er
 14. &Queensborough&&     Palmer \&&&      1182&\cr
 15. &             &&     \ \ Hornbostel&&       &\er
 16. &             &&               && 1380&\cr
 17. &Triborough&&        O. H. Ammann&&
 18.   \omit\leaders\hrule height 3pt depth -2.6pt\hfill&\cr
 19. &                &&              &&   ?383&\er
 20. &Bronx Whitestone&&  O. H. Ammann&&   2300&\cr
 21. &Throgs Neck&&       O. H. Ammann&&   1800&\er
 22. &George Washington&& O. H. Ammann&&   3500&\er
 23. }}}
 24. \mktable{0}{}%
 25. \mktable{1}{spread 20pt}%
 26. \moveleft0.5in\hbox{\box0\hskip4pt\box1}
Produces: See typeset version.

Comments:

  • The table in this example is typeset twice (lines 24-26). The version on the right is 20 points wider than the version on the left. It is the \tabskip glue that makes this possible (lines 2 and 7-8).
  • Actually, this example is a hybrid. It uses \tabskip to set the intercolumn glue except for the Length column where the glue is explicitly set (lines 3 and 8).
  • Tabskip glue remains after an \omit. I could only make the rule (line 18) separating the lengths of the two segments of the Triborough bridge completely fill its column by setting \tabskip to zero in that column.
  • The preamble uses `##' instead of the normal `#' (lines 7-8). This is because the \halign{} occurs inside a \def where `#' means parameter. In fact parameter 1 is the box number to use (line 5), and parameter 2 is the spread statement to add after the \halign (line 6).
  • The code which makes the `?" work on line 19 is not shown. The example on the \span reference page uses `?' and explains how it works.
  • The table is from ``Tbl-A Program to Format Tables,'' by M. E. Lesk which in turn begins on page 157 of Unix Programmer's Manual, Volume 2, 1983.
TeXbook References: 237-238. Also: 215, 237-239, 244, 247, 274, 282, 285, 354.

Related Primitives: halign, valign.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

textfont Math (Fonts)
Internal Quantity
Synopsis: \textfont<4-bit family number>=<font identifier>

Description:

    WHEN TeX is in math mode, it typsets material using one of 16 families of fonts. Each family has three fonts: text, script, and scriptscript. The text, script, and scriptscript styles use the corresponding font. Also, the display styles use the text font. The \textfont command identifies a control sequence (obtained using the \font command) with the text font of a particular family. The command generates an error if the family number is not in the range 0-15. Any font may be placed in any family with the restriction that fonts in families 2 and 3 are required to have extra special parameters [153]. Math glue is defined using mu units. There are 18 mu in one em, and in text style, the em is taken from \textfont2 (the math symbols family) [168].
Example:

  1. \def\tmathfont#1#2#3% identifier + fonts for families 0 & 1.
  2. {%
  3.   \begingroup
  4.     \textfont0=#2
  5.     \textfont1=#3
  6.     \edef\rm{\fam0#2}
  7.     \parindent=1.5pc
  8.     \noindent #1. Font 0 is: \fontname\textfont0, and
  9.                   font 1 is: \fontname\textfont1.
 10.     Space widths are: \the\fontdimen2\textfont0\ and
 11.                       \the\fontdimen2\textfont1.\par
 12.     ${\rm A.\ If\ } i {\rm\ is\ prime\ to\ }m, {\rm the\ congruence\ }
 13.     ix \equiv 1 \hbox{ (mod $m$) has just 1 root. Also, \dots}$\par % p 88.
 14.     $f(x) = 3x^2 + 2x - 1$ \par
 15.   \endgroup
 16. }
 17. \tmathfont{1}{\tenrm}{\teni}% CM fonts. Makes Plain TeX values.
 18. \tmathfont{2}{\teni}{\tenrm}% Reverses roman & italics from 1.
 19. \tmathfont{3}{\rm}{\it}%      Caslon 224 roman & italics.
 20. Compare the Caslon `A' with the CM `{\tenrm A}'.
Produces: See typeset version.

Comments:

  • This example illustrates several pitfalls of setting up fonts for mathematics.
  • Lines 1-16 define the macro \tmathfont. It gives temporary values to text fonts 0 and 1. The definition of \rm on line 6 is consistent with how Plain TeX works.
  • Lines 8-11 typeset the file names used for the two fonts and show the width of a space in each font.
  • Lines 12-13 typeset a statement mixing text with in-line mathematics. The text is set using both `{\rm ...}' and `\hbox{...}'.
  • Finally, lines 17-19 prepare three different examples. The first uses the fonts from Plain TeX; the second switches those two fonts; and the third uses Caslon roman and italics fonts.
  • In each example the \rm text actually uses textfont0 (compare the `A' made by line 12 with the ones made by line 20), and the \hbox uses the non-math mode font which is Caslon in all three examples.
  • Interword spaces disappear in example 2 because the space width of cmmi10 is 0pt.
  • Also, example 2 uses the wrong symbols in a number of places. A comparison of the font tables for cmr10 and cmmi10 should explain why [427, 430].
  • Finally, the font tables and Plain TeX's definition of \dots explain why the `...' at the end of line 13 is messed up by examples 2 and 3.
TeXbook References: 153. Also: 153, 168, 188, 213, 271, 351, 414-415, 441-442.

Related Primitives: scriptfont, scriptscriptfont, font, fam, displaystyle, textstyle.

For Additional Examples, see: mathchar, scriptfont, scriptscriptfont

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

textstyle Math
Command
Synopsis: \textstyle

Description:

    THIS command is used to specify text style. TeX uses four main styles to typeset formulas and subformulas: display, text, script, and scriptscript. Each main style has a corresponding cramped style. The eight styles are referred to as: D, D', T, T', S, S', SS, and SS' where the primed letter means the cramped style. TeX uses the text font (\textfont) for the current family (\fam) when it typesets material in display and text styles (both regular and cramped) [140]. The body of the following table lists the style of the major components in a formula whose basic style is known:
    component in formula | current style of formula
 | D | D' | T | T' | S, SS | S', SS'
superscript | S | S' | S | S' | SS | SS'
subscript | S' | S' | S' | S' | SS' | SS'
numerator | T | T' | S | S' | SS | SS'
denominator | T' | T' | S' | S' | SS' | SS'
    Finally, \underline does not change style, but \overline, \sqrt, and math accents change regular styles to cramped ones [141].
Example:

  1. \def\mkcstyle#1#2%
  2. {%
  3.      \vbox to 0pt
  4.      {%
  5.           \vss
  6.           \hbox{$#1{\atop #2^2}$}%
  7.           \kern0pt
  8.      }%
  9. }
 10. \halign{#\hfil&&\quad#\hfil\cr
 11. \it D&\it T&\it D\ftB, T\ftB&\it S&\it S\ftB&\it SS&\it SS\ftB\cr
 12. \noalign{\vskip2pt\hrule\vskip3pt}
 13. $\displaystyle x^2$&$x^2$&\mkcstyle{\displaystyle}{x}&
 14. $\scriptstyle x^2$&\mkcstyle{\textstyle}{x}&
 15. $\scriptscriptstyle x^2$&\mkcstyle{\scriptstyle}{x}\cr
 16. $\displaystyle X^2$&$X^2$&\mkcstyle{\displaystyle}{X}&
 17. $\scriptstyle X^2$&\mkcstyle{\textstyle}{X}&
 18. $\scriptscriptstyle X^2$&\mkcstyle{\scriptstyle}{X}\cr}
Produces: See typeset version.

Comments:

  • This example makes a table showing each of the styles. The table only has seven columns because cramped display style is the same as cramped text style.
  • Lines 1-9 define a macro which is used to coerce an expression into one of the cramped styles. The macro is a variation of ideas on page 141 of the actual tex file for The TeXbook.
  • The height of the superscript is different in each column. This is particularly apparent on the second line which uses an uppercase `X'.
TeXbook References: 140-141. Also: 140-142, 292, 326.

Related Primitives: displaystyle, scriptstyle, scriptscriptstyle, textfont, fam.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

the Macro
Command
Synopsis: \the<internal quantity>

Description:

    THIS command is used in 3 ways: a) it typesets the value of one of the parameters (integer, dimen, glue, or muglue) or one of the internal quantities (except \font) [214]; b) \the\font returns a control sequence for the current font; and c) \the<token parameter> produces a copy of the token list for the token parameter [215]. The internal quantites are listed on page 271 of The TeXbook, and the parameters are listed on pages 272-275. Each of the reference pages in this book includes the primitive's type near the top of the page. This was done in part so it would be clear if \the could be used with the primitive or not.
Example:

  1. \def\tprim#1{#1 = \the\csname #1\endcsname}
  2. Here are some internal quantities: \tprim{inputlineno}; \tprim{spacefactor}\par
  3. Here are some integer parameters: \tprim{widowpenalty}; \tprim{showboxdepth}\par
  4. Here are some dimen parameters: \tprim{hsize}; \tprim{vsize}\par
  5. Here are some glue parameters: \tprim{baselineskip}; \tprim{topskip}\par
  6. Here are some muglue parameters: \tprim{thinmuskip}\par
  7. Here are some internal quantities: \tprim{inputlineno}; count0 = \the\count0\par
Produces: See typeset version.

Comments:

  • Line 1 provides a interesting use of \csname.
  • Lines 2-6 illustrate many of the types of primitives that may be used after \the.
  • The value of \inputlineno on line 7 should be 5 greater than the value on line 2 since it is kept up-to-date on a line by line basis. However, the value of \count0 may be out of sync with the page number.
TeXbook References: 214, 271-275. Also: 214-216, 373, 375, 422.

Related Primitives: showthe.

For Additional Examples, see: day, divide, ifnum, pagedepth

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

thickmuskip Math (Glue)
5mu plus 5mu * Parameter (muglue)
Synopsis: \thickmuskip<muglue>

Description:

    THIS parameter holds the math glue used by thick spaces [168]. TeX inserts thin, medium, and thick spaces in math formulas automatically [167]. For example, TeX puts a thick space between ordinary and relation atoms in display and text styles [170]. Each type of space is a form of math glue and is expressed using mu units. There are 18mu in an em where the em is from family 2 (the math symbols font). In particular, the size of a mu depends on the current style since each style normally has a different size and hense a different em value. Math glue can stretch and shrink, and the Plain TeX value for \thickmuskip has a stretch component but not a shrink component [168].
Example:

     \def\tf#1#2#3#4% glue for thin, medium, and thick skips & equation #.
     {%
          \thinmuskip=#1%
          \medmuskip=#2%
          \thickmuskip=#3%
          $$F_n = F_{n-1} + F_{n-2} \hbox{, for } n \ge 2\leqno(#4.)$$
     }
     The Fibonacci numbers are defined by: $F_0=1$, $F_1=1$, and
     \tf{3mu}{4mu plus 2mu minus 4mu}{5mu plus 5mu}1
     \tf{3mu}{4mu plus 2mu minus 4mu}{0mu}2
     \tf{0mu}{0mu}{0mu}3
Produces: See typeset version.

Comments:

  • This example typesets the recursive definition of the Fibonacci numbers three times: the first uses Plain TeX values for the three spaces; the second makes the thick space zero; and the third makes all spaces zero.
TeXbook References: 168, 170. Also: 167-168, 170, 274, 349, 446.

Related Primitives: mskip, thinmuskip, medmuskip.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

thinmuskip Math (Glue)
3mu * Parameter (muglue)
Synopsis: \thinmuskip<muglue>

Description:

    THIS parameter holds the math glue used by thin spaces [168]. TeX inserts thin, medium, and thick spaces in math formulas automatically [167]. For example, TeX puts a thin space between ordinary and operator atoms [170]. Each type of space is a form of math glue and is expressed using mu units. There are 18mu in an em where the em is from family 2 (the math symbols font). In particular the size of a mu depends on the current style since each style normally has a different size and hense a different em value. Although math glue can stretch and shrink, the Plain TeX value for \thinmuskip does not [168].
Example:

  1.
  2. $\sqrt 2 x$ vs $\sqrt 2\,x$\hskip0.5in           % \def\,{\mskip\thinmuskip}
  3. $\sqrt{\log x}$ vs $\sqrt{\,\log x}$\hskip0.5in  % \def\!{\mskip-\thinmuskip}
  4. $O\bigl({1/\sqrt n}\bigr)$ vs $O\bigl({1/ \sqrt n}\,\bigr)$\par
  5. \vskip0.5\baselineskip
  6. $[0,1)$ vs $[\,0,1)$\hskip0.5in
  7. $x^2/2$ vs $x^2\!/2$\hskip0.5in
  8. $\int_0^x\int_0^y dF(x,y)$ vs $\int_0^x\!\int_0^y dF(x,y)$\par
  9. $$\int\int_D dxdy
 10. \hskip6pt \int\!\int_D dx\,dy
 11. \hskip6pt \int\!\!\int_D dx\,\,dy
 12. \hskip6pt \int\!\!\!\int_D dx\,\,\,dy
 13. \hskip6pt \int\!\!\!\!\int_D dx\,\,\,\,dy
 14. \hskip6pt \int\!\!\!\!\!\int_D dx\,\,\,\,\,dy
 15. \hskip6pt \int\!\!\!\int_D dx\,dy$$
Produces: See typeset version.

Comments:

  • TeX does a good job adding space to many expressions, but occasionally it needs help. This example shows how adding a positive or negative thin space can improve the looks of an expression.
  • Lines 1-3 and 5-7 typeset six expressions twice: the first uses TeX's spacing; and the second uses adjusted spacing.
  • Lines 8-14 show that sometimes more than one correction is needed. The first expression is unadjusted, and the last is the author's preference. The middle ones show a number of different options for the space between the integrals and the differentials.
TeXbook References: 168, 170. Also: 167-168, 170, 274, 349, 446.

Related Primitives: mskip, medmuskip, thickmuskip.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

time Job
Parameter (integer)
Synopsis: \time

Description:

    THIS parameter is set at the beginning of a job to the current time in minutes after midnight. It ranges from 0 to 1439 [349].
Example:

  1. \def\mytimeA#1%format #1 (usually \the\time) using a.m. & p.m.
  2. {%
  3.   {%
  4.      \count20=#1 %
  5.      \count22=\count20
  6.      \divide \count20 by 60
  7.      \count21=\count20
  8.      \multiply\count21 by -60
  9.      \advance\count22 by \count21
 10.      \ifnum\count20<12
 11.           \def\tapm{ a.m.}%
 12.      \else
 13.           \def\tapm{ p.m.}%
 14.      \fi
 15.      \ifnum\count20=0
 16.           \count20=12
 17.      \fi
 18.      \ifnum\count20>12
 19.           \advance\count20 by -12
 20.      \fi
 21.      \the\count20:%
 22.      \ifnum\count22<10 0\fi
 23.      \the\count22
 24.      \tapm
 25.   }%
 26. }
 27. \mytimeA{0}---\mytimeA{30}---\mytimeA{90}---\mytimeA{720}---%
 28. \mytimeA{750}---\mytimeA{1410}\par
 29. \count20=-100
 30. Time is: \the\time, and count20 = \the\count20.\par
 31. Better time is: \mytimeA{\the\time}, and count20 = \the\count20.
Produces: See typeset version.

Comments:

  • This shows one way to convert \time to civilian time.
  • The hours are calculated in register 20 and the minutes in register 22. The basic calculations are made on lines 6-9. Then lines 10-20 set up `a.m.' and `p.m.' and make several adjustments for special cases.
  • The special cases require checking. That is why the time is passed as a parameter to \mytimeA. Lines 27-28 show things work at several special times.
  • The grouping done by lines 3 and 25 ensure that the registers used on lines 4-23 will not interfere with other uses of the registers outside of \mytimeA.
  • The \ifnum reference page contains a macro which makes military time.
TeXbook References: 349. Also: 273, 349.

Related Primitives: day, month, year.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

toks Registers
Internal Quantity
Synopsis: \toks<8-bit register number>={<replacement text>}

Description:

    THERE are 256 toks registers: \toks0 to \toks255. Each may hold a token list [212]. The toks registers obey TeX's grouping structure. So, changes to a register inside a group will not affect the value of the register outside the group unless \global was used with the register [nr]. The command `\showthe\toks n' writes the contents of \toks n to the terminal and to the log file. Also, the command `\the\toks n' typesets the contents of \toks n [215].
TeXbook References: 212. Also: 212, 215, 262, 276.

Related Primitives: toksdef.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

toksdef Registers
Command
Synopsis: \toksdef<name>=<8-bit register number>

Description:

    A toks register may be used directly (e.g., `\toks25 = {\noindent Hello}') [118] or indirectly in one of two ways. Each indirect way involves setting up a symbolic name for a register (e.g., \greeting). The first indirect way uses the primitive \toksdef (e.g., `\toksdef\greeting=25'); this makes \greeting equivalent to \toks25. So, the command `\greeting = {\noindent Hello}' sets up a token list. The second indirect way uses the Plain TeX command \newtoks (e.g., `\newtoks\greeting'). This time the control sequence \greeting is a toks register, but it is not at all apparent which one (the log file should contain a line `\greeting=\toks n' for some n) [212]. The direct method is fine for registers used locally in a macro or in a group. The \newtoks method (or something equivalent if Plain TeX is not used) is the preferable indirect method. If macros from several sources are used, and two different \toksdef's use the same register number, the macros may interfere with each other. This type of problem is difficult to track down [nr]. TeX suppresses expansion when it is reading a control sequence that will be defined by a \toksdef [215].
TeXbook References: 212. Also: 212, 215, 277, 347, 378.

Related Primitives: toks.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

tolerance Paragraph
200 * Parameter (integer)
Synopsis: \tolerance=<number>

Description:

    TEX will make up to three attempts to break a paragraph into lines. If the first attempt using \pretolerance fails, TeX hyphenates every work in the paragraph. Then, it tries to find breaks so that each line has \badness no larger than \tolerance. Since \badness is at most 10,000, setting \tolerance=10000 will always allow TeX to find line breaks. But the results may be poor [96]. The third attempt uses \emergencystretch [107].
Example:

     \hsize=1.25in\parindent=0pt
     \pretolerance=100
     \tolerance=200
     \emergencystretch=0pt
     \setbox0=\vtop{\tstory\par}%       The \adjdemerits reference page holds
     \setbox1=\vtop{\tolerance=10000 %  the definition of \tstory
     \tstory\par}
     \setbox2=\vtop{\emergencystretch=1.65em
     \tstory\par}
     \hbox to 5.0in{\box0\hfil\box1\hfil\box2}
Produces: See typeset version.

Comments:

  • The paragraph on the left uses default values for \pretolerance, \tolerance, and \emergencystretch. It has numerous overfull boxes.
  • The middle paragraph sets \tolerance to its maximum value. Although the overfull boxes go away, two lines are quite poor.
  • The paragraph on the right sets \emergencystretch to 1.65em (several values were tried before the 1.65 was selected). It still has several poor lines, but no real disasters.
TeXbook References: 96, 107. Also: 29-30, 91, 94, 96, 107, 272, 317, 333, 342, 348, 364, 451.

Related Primitives: pretolerance, emergencystretch, badness.

For Additional Examples, see: pretolerance

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

topmark Marks
Command
Synopsis: \topmark

Description:

    THIS command holds the value that \botmark had on the previous page. It is null (i.e., empty) before the first page. It is equal to the previous \botmark, when a page contains no marks [258]. The value of \topmark is global (i.e., it is not affected by grouping) [259].
Example:

  1. % These lines are from the macro that makes the reference page
  2. % for a control sequence.
  3. % We have: \def\CScs{ControlSequence}, e.g., \def\CScs{topmark}
  4. % \box0 holds everything through the Synopsis line.
  5.      \mark{\currentcs\noexpand\else\CScs}% This is first  of 2 marks made.
  6. % Do \eject unless following \box0 will fit on current page.
  7. % The \ifdim reference page shows this test.
  8.      \unvbox0%
  9.      \mark{\CScs\noexpand\else\CScs}%      This is second of 2 marks made.
 10. % Typeset the rest of the page.
 11.      \let\currentcs=\CScs
Produces: See typeset version.

Comments:

  • It is tricky to get the correct guide word on the header line of these reference pages. Two things are required [260-261].
  • First, a special mark is made before and after the start of each control sequence (lines 5 and 9). Each mark contains two options separated by `\noexpand\else'.
  • Second, the header routine for verso (left-hand or even) pages selects the page's guide word with the test: `\iffalse\topmark\fi'.
  • Lines 5 and 9 show the \iffalse statement always expands to \CScs, but the value for \CScs depends on whether a new command starts at the top of the current verso page (assumed to be 100) or not. If it does, the previous page is ejected by lines 6-7. So the last mark on page 99 is made by line 5. That mark becomes page 99's \botmark. Hense, it becomes page 100's \topmark. But the \CScs that occurs on line 5 is the control sequence that starts on page 100. So, the guide word is correct. If page 100 continues a command begun earlier, the \botmark on page 99 was made by the mark on line 9. The \CScs on that line is the one for the command that continues onto page 100. Hense, the guide word is also correct in this case.
TeXbook References: 258-260. Also: 213, 258, 259-260, 280.

Related Primitives: mark, firstmark, botmark.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

topskip Page
10pt * Parameter (glue)
Synopsis: \topskip=<glue>

Description:

    IDEALLY, the baseline of the first box or line of text on each new page will be at the same position at the top of the page. TeX uses glue provided by \topskip to accomplish that. Just before the first box is added to the page, TeX computes `g = \topskip - height of first box'. If g is negative, it is set equal to zero. Also, if \topskip has a stretch or shrink component it is added to g. Finally, TeX inserts `\vskip g' just before it adds the first box to the new page [114].
TeXbook References: 113-114. Also: 113-114, 124, 256, 274, 348.

Related Primitives: vsize, splittopskip.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

tracingcommands Debugging
0 * Parameter (integer)
Synopsis: \tracingcommands=<number>

Description:

    IF this parameter is positive, TeX writes every command it executes to the log file [88]. If it is 2 or larger, TeX also writes all conditional commands and their outcomes [212]. This may help reveal extra blank spaces which are left in a macro [299]. If \tracingonline is positive, the commands are also displayed on the terminal [303].
Example:

  1. \def\checkit#1#2% The next line has a missing % !
  2. {
  3.      \setbox0=\hbox{#1}%
  4.      \ifdim\wd0 > #2%
  5.           Too wide!%
  6.      \else
  7.          \box0
  8.      \fi
  9. }
 10. \tracingcommands=1
 11. ---\checkit{Hello World}{60pt}\par
 12. \tracingcommands=0
 13. \message{Try a new one}
 14. \tracingcommands=2
 15. ---\checkit{Hello World}{20pt} Sorry.
 16. \tracingcommands=0
Produces: See typeset version.

Comments:

  • Lines 1-9 define a macro, and lines 10-16 use it twice.
  • The first time tracingcommands is equal to one. This writes lines 17-25 to the log file.
  • The second time tracingcommands is equal to two. This writes lines 27-42 to the log file.
  • The macro inserts an extra space because of a missing % at the end of line 2. In the author's opinion neither set of material written to the log file is particularly helpful in this example in locating the space since the parameter and the macro contain blank spaces which show up in the log file and are not extra (e.g., line 20)! However, I have found the command helpful with other material.
TeXbook References: 88, 212. Also: 88-89, 212, 273, 299.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

tracinglostchars Debugging
1 * Parameter (integer)
Synopsis: \tracinglostchars=<number>

Description:

    A font may not have a character in all of the 256 possible positions. If this parameter is positive, TeX writes a missing character message to the log file each time it encounters a character which is not defined in the current font [301]. If \tracingonline is positive, the message is also displayed on the terminal [303].
Example:

  1. \newlinechar=`@
  2. \tracinglostchars=1
  3. \message{Check for missing characters.@}
  4. 1. \char247\char250\char251\char254\quad% 250 = "fa.
  5. \message{Try it now.@}
  6. \tracinglostchars=0
  7. 2. \char247\char250\char251\char254
  8. \message{Did we catch them?@}
Produces: See typeset version.

Comments:

  • Lines 4 and 7 try to typeset four non-standard characters. Only the first and fourth are actually typeset. Caslon 224, with the encoding used on these pages, does not have characters in positions 250 and 251.
  • Lines 10-11 are made when \tracinglostchars=1. They catch the missing characters on line 4. Line 6 changes \tracinglostchars back to zero. Now, TeX does not catch the missing characters on line 7.
TeXbook References: 301. Also: 273, 301, 348, 401.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

tracingmacros Debugging
0 * Parameter (integer)
Synopsis: \tracingmacros=<number>

Description:

    IF this parameter is positive, TeX writes the expansion of each macro it encounters and the arguments for the macro to the log file. If it is 2 or larger, TeX also writes the expansion of the token lists parameters (e.g., \output, \everypar, \everymath, ....) [212]. If \tracingonline is positive, the material is also displayed on the terminal [303].
Example:

  1. \def\checkit#1#2%
  2. {%
  3.      \setbox0=\hbox{#1}%
  4.      \ifdim\wd0 > #2%
  5.           Too wide!%
  6.      \else
  7.          \box0
  8.      \fi
  9. }
 10. \tracingmacros=1
 11. \checkit{Hello World}{60pt}\par
 12. \checkit{Hello World}{20pt} Sorry.
 13. \tracingmacros=0
Produces: See typeset version.

Comments:

  • The \tracingmacros command on line 10 makes TeX write the expansion of the following two lines to the log file. That makes lines 14-16 and 18-20.
TeXbook References: 205, 212. Also: 205, 212, 273, 329.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

tracingonline Debugging
0 * Parameter (integer)
Synopsis: \tracingonline=<number>

Description:

    IF this parameter is positive, TeX displays output from the various `\tracing...' commands on the terminal in addition to writing it to the log file [303]. On the author's system this was the case for all commands execpt \tracingstats whose output was only written to the log file.
TeXbook References: 303. Also: 121, 212, 273, 303.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

tracingoutput Debugging
0 * Parameter (integer)
Synopsis: \tracingoutput=<number>

Description:

    IF this parameter is positive when \shipout<box> is encountered, TeX writes the contents of the box to the log file [254]. The values of \showboxbreadth and \showboxdepth control the amount of the box that is written [302]. If \tracingonline is positive, TeX also displays the contents of the box on the terminal [303].
Example:

  1. \setbox0=\boxit{\hbox{A}}%
  2. \setbox1=\hbox{B}%
  3. \setbox2=\hbox{\boxit{\copy0}\kern25pt\boxit{\copy1}}%
  4. \setbox3=\boxit{\box2}
  5. \copy3
  6. \showboxdepth=2
  7. \showboxbreadth=4
  8. \tracingoutput=1
  9. \vfill\eject
 10. \tracingoutput=0
Produces: See typeset version.

Comments:

  • Output boxes tend to be hugh. The one for the above example is 178 lines long. The length is due in part to identification material my formatting routines place at the top of each page outside the final printed page margins.
  • The small values for \showboxbreadth and \showboxdepth on lines 6-7 limit what TeX writes to the log file because of the \eject on line 9.
TeXbook References: 254. Also: 254, 273, 301-302.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

tracingpages Debugging
0 * Parameter (integer)
Synopsis: \tracingpages=<number>

Description:

    IF this parameter is positive, TeX writes the page-cost calculations to the log file [112]. If \tracingonline is positive, TeX also displays the calculations on the terminal. Some versions of TeX don't look at \tracingpages [303]. The calculations are written a paragraph at a time. That means the calculations may be interrupted by other material that is also being written to the log file [nr].
Example:

     \tracingpages=1
     % Put `critical' lines here . . .
     \tracingpages=0
Produces: See typeset version.

Comments:

  • TeX writes the page-cost calculations to the log file for the critical lines. Those calculations show the value of each nonzero `page...' item (except \pagedepth) as each critical line is added to the current page [112].
  • The above lines are from page 285 of an early draft of the reference pages.
TeXbook References: 112-113. Also: 112-114, 124, 273, 303.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

tracingparagraphs Debugging
0 * Parameter (integer)
Synopsis: \tracingparagraphs=<number>

Description:

    IF this parameter is positive, TeX writes the line-breaking calculations to the log file [98]. If \tracingonline is positive, TeX also displays the calculations on the terminal. Some versions of TeX don't look at \tracingparagraphs [303].
Example:

  1. \tracingparagraphs=1
  2. \dropcap{}{I}F this parameter is positive, \tex\ writes the
  3. line-breaking calculations to the log file \tr{98}. If
  4. |\tracingonline| is positive, the calculations are also displayed on
  5. the terminal. Some versions of \tex\ don't look at this parameter
  6. \tr{303}.
Produces: See typeset version.

Comments:

  • Lines 2-6 typeset a draft version of the Description paragraph for \tracingparagraphs.
  • Line 1 tells TeX to write its line-breaking calculations to the log file.
  • Lines 7-30 show those calculations. This material can become quite long, and \showboxdepth and \showboxbreadth do not limit what TeX writes to the log file.
TeXbook References: 98-99. Also: 98-99, 273, 303.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

tracingrestores Debugging
0 * Parameter (integer)
Synopsis: \tracingrestores=<number>

Description:

    IF this parameter is positive, TeX displays items removed from the save stack at the end of a group. This may help track down variables which are given both local and global values [301]. If \tracingonline is positive, TeX also displays the calculations on the terminal. Some versions of TeX don't look at \tracingrestores [303].
Example:

  1. \newlinechar=`@     % makes \message{} start on new line.
  2. \newcount\tnum
  3. \def\l{\advance\tnum by 1}
  4. \def\g{\global\advance\tnum by 1}
  5. \tnum=1
  6. \message{1. at start: tnum=\the\tnum @}
  7. \tracingrestores=1
  8. \bgroup
  9.      \message{2. new group@}
 10.      \l\g\l
 11.      {
 12.           \message{3. new group@}
 13.           \l\g\l
 14.           {
 15.                \message{4. new group@}
 16.                \g\g\g
 17.           }
 18.           \message{5. exiting group, tnum=\the\tnum @}
 19.      }
 20.      \message{6. exiting group, tnum=\the\tnum @}
 21.      \g\l
 22. \egroup
 23. \message{7. exiting group, tnum=\the\tnum @}
 24. \tracingrestores=0
Produces: See typeset version.

Comments:

  • Lines 2-5 allocate a new count register; define macros which make local and global references to the register; and initialize the register.
  • Lines 8-22 contain three nested groups. TeX writes a message to the log file when it enters and leaves each group. In addition, the assignment made to \tracingrestores on line 7 causes TeX to write five additional lines to the log file.
  • The inner-most group (lines 14-17) makes three global references to the count register. None of them appear in the log file (see lines 29-30).
  • The middle group (lines 11-13 and 19) makes two local references to the count register. They appear on lines 31-32 of the log file.
  • The outer group (lines 8-10 and 20-22) makes three local references to the count register. They appear on lines 34-36 of the log file.
TeXbook References: 301. Also: 273, 301, 303.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

tracingstats Debugging
0 * Parameter (integer)
Synopsis: \tracingstats=<number>

Description:

    IF this parameter is positive, TeX writes statistics about memory usage at the end of the log file. In addition if the parameter is 2 or larger, it writes a simplified version of the statistics each time it encounters a \shipout command [300]. Some versions of TeX don't look at \tracingstats [303]. On the author's system the \tracingonline parameter is ignored with \tracingstats.
    The following items are written:
    item | description
number of strings | names of control sequences and files.
pool size | the characters in such names.
main memory size | boxes, glue, breakpoints, token lists, characters, etc.
hash size | control sequence names.
font memory | font metric data.
exception dictionary | hyphenation exceptions.
input stack size | simultaneous input sources.
semantic nest size | unfinished lists being constructed
parameter stack size | macro parameters.
buffer size | characters in lines being read from files.
save size | values to restore at group ends.
Comments:

  • The above log file data is from a 600+K tex file that produced a 1.8+M ps file which contained 313 typeset pages.
  • Lines 2-7 in the file are easily identified with the first six items in the table in the Description area. Each of the last five items in the table has a letter in bold. That letter matches a letter following one of the five items on line 8.
  • The only items that are close to their limits are the 123 fonts out of 255 and the 2185b (buffer size) out of 3000. I find the limit of 255 fonts to be a problem, and I've had to change the way I work with PostScript fonts to stay inside TeX's limit. The buffer size limit is misleading. TeX reads a complete line from the source file and puts it in a buffer which has room for 3000 characters. I work with a text editor that treats each paragraph as a single line. Apparently, one paragraph contained 2185 characters. However, I can easily tell the editor to break a paragraph into lines containing no more than 80 characters. So, I am not concerned by the large buffer size value.
TeXbook References: 300. Also: 273, 300, 303, 383.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

uccode Character
Internal Quantity
Synopsis: \uccode<8-bit number>

Description:

    THIS quantity is used by \uppercase to convert a character to its uppercase equivalent [41]. INITEX sets \uccode`a=`A and \uccode`A=`A. It makes similar assignments for all other letters. Finally, it makes the \uccode of all nonletters zero [345].
Example:

  1. \bgroup
  2. \uccode`m=`*
  3. Many mops are floppy!\par
  4. \uppercase{m}any mops are floppy!\par
  5. %
  6. \romannumeral -1 A\par
  7. \romannumeral 1000 B\par
  8. \romannumeral 5000 C\par
  9. \romannumeral 10000 D\par
 10. \uppercase\expandafter{\romannumeral 50000} E\par
 11. \egroup
 12. \def\astsA#1#2%char to typeset, # of times. See TTB [373-374}.
 13. {%
 14.   \bgroup
 15.      #2 #1's:\quad
 16.      \count1=#2
 17.      \multiply\count1 by 1000
 18.      \uccode`m=`#1
 19.      \tt\uppercase\expandafter{\romannumeral\number\count1}%
 20.   \egroup
 21. }
 22. \astsA{*}{10}\par
 23. \astsA{a}{20}\par
 24. \astsA{A}{30}\par
 25. \astsA{^^b3}{35}\par% see TTB [45} for ^^xx.
 26. \astsA{?}{40}\par
Produces: See typeset version.

Comments:

  • Generally, changes to \uccode values should be done inside a group.
  • Lines 3-4 are a silly example that changes the uppercase of `m' to `*'.
  • Lines 6-9 illustrate several boundary tests of \romannumeral. The results of those lines suggested line 10 which in turn suggested lines 12-26. They form the real example here.
  • Pages 373-374 of The TeXbook discuss several ways to typeset an arbitary number of *'s. Most of the ways involve a loop (which is slow) or have other undesirable side effects.
  • Lines 12-21 define a macro which uses \uccode and romannumeral to typeset an arbitary number of any character. I got the idea for \astsA while trying to `break' \romannumeral (e.g., lines 6, 8, and 9).
TeXbook References: 41. Also: 41, 214, 271, 345, 348, 377, 394.

Related Primitives: lccode, catcode, sfcode, uppercase.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

uchyph Hyphenation
1 * Parameter (integer)
Synopsis: \uchyph

Description:

    TEX does not try to hyphenate words whose first character is uppercase (i.e., is equal to its own \uccode) unless this parameter is positive [454]. Changes made to \uchyph are local to the group containing the change [nr].
Example:

  1. \def\tstoryA{There are cries, sobs, confusion among the people, and at
  2. that Moment the cardinal himself, the Grand Inquisitor, passes by the
  3. cathedral. He is an old man . . .}
  4. \count0=\uchyph
  5. \setbox0=\vbox{\hsize=2.25in \tstoryA}
  6. \setbox1=\vbox{\hsize=2.25in\uchyph=0 \tstoryA}
  7. \hbox to \hsize{\box0\hfill\box1}
  8. The values are: \the\count0\ and \the\uchyph
Produces: See typeset version.

Comments:

  • Setting \uchyph=0 on line 6 stopped TeX from hyphenating Moment on line 2.
  • Lines 4 and 8 show the change made to \uchyph on line 6 is local.
TeXbook References: 454. Also: 273, 348, 454.

Related Primitives: uccode.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

underline Math
Command
Synopsis: \underline<character or {subformula}>

Description:

    THIS command places a line under the following character or subformula [131]. The command does not change styles [141].
Example:

     \def\ta{\underline}
     To summarize: if $ x + y = z$,
     $\ta x + \ta y = \ta z $,
      and $\ta{x_2} + \ta{y_2} = \ta{z_2}$,
     then $\ta{\ta{x_2} + \ta{y_2}} = \ta{\ta{z_2}}$.\par
     Of course, $ \ta l + \ta m \ne \ta j $.
Produces: See typeset version.

Comments:

  • The mathematics is nonsense, but it shows TeX appropriately positions a line for the depth and width of the material it is under.
TeXbook References: 130-131. Also: 130-131, 141, 291, 443.

Related Primitives: overline.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

unhbox Box
Command
Synopsis: \unhbox<8-bit register number>

Description:

    THIS command is similar to \box except it unsets glue at the box's outermost level [120]. Also, the box register must either contain an \hbox or be empty [285]. In horizontal mode nothing happens if the register is empty, and the horizontal list in the register is added without change to the current list if it is not [285]. In vertical mode a new paragraph is begun; the \indent command is performed; the tokens in \everypar are added to the new horizontal list; and the contents of the \hbox are added to that list [283]. In math mode the register must be empty [293]. After an \unhbox command the box register is empty [285].
Example:

     \parindent=0pt
     \setbox0=\hbox{Watch this}
     \setbox1=\hbox{line closely.}
     \setbox2=\hbox{\copy0\ \copy1}
     \setbox3=\hbox spread 2em{\copy0\ \copy1}
     \setbox4=\hbox spread 2em{\unhcopy0\ \unhcopy1}
     \setbox5=\hbox{\copy4}
     c2. \copy2\par
     u2. \unhbox2\par
     c3. \copy3\par
     u3. \unhbox3\par
     c4. \copy4\par
     u4. \unhbox4\par
     u5. \unhbox5\par
Produces: See typeset version.

Comments:

  • The code before each line in the Produces area shows whether the line arose from a copy or unbox operation. It also shows the box number used to make the line.
  • Box 2 contains two boxes and a space. Nothing unusual happens to it when the box is copied or unboxed.
  • Box 3 is the same as box 2 except it is 2 ems wider than box 2. When box 3 is copied, the extra 2 ems goes into the single space. But, when it is unboxed, the extra 2 ems goes away.
  • Box 4 may look like box 3, but actually, it is quite different. It holds 4 words and 3 spaces. Thus, when it is copied, the extra 2 ems is split evenly between the 3 spaces. But, when it is unboxed, the extra space goes away just as it did for box 3.
  • Box 5 is a copy of box 4 and so holds 1 item. When the box is unboxed, there is nothing to throw away. That is why the `u5' line has the extra space in it.
TeXbook References: 120. Also: 120, 283, 285, 293, 354, 356, 399.

Related Primitives: unhcopy, box.

For Additional Examples, see: afterassignment, setbox

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

unhcopy Box
Command
Synopsis: \unhcopy<8-bit register number>

Description:

    THIS command is similar to \copy except it unsets glue at the box's outermost level [120]. Also, the box register must either contain a \hbox or be empty [285]. In horizontal mode nothing happens if the register is empty, and the horizontal list in the register is added without change to the current list if it is not [285]. In vertical mode a new paragraph is begun; the \indent command is performed; the tokens in \everypar are added to the new horizontal list; and the contents of the \hbox are added to that list [283]. In math mode the register must be empty [293]. The box register is unchanged by an \unhcopy command [285].
Example:

     \parindent=0pt
     \setbox0=\hbox{Watch this}
     \setbox1=\hbox{line closely.}
     \setbox2=\hbox{\copy0\ \copy1}
     \setbox3=\hbox to 120pt{\copy0\ \copy1}
     \setbox4=\hbox to 120pt{\unhcopy0\ \unhcopy1}
     \setbox5=\hbox{\copy4}
     c2. \copy2\par
     u2. \unhcopy2\par
     c3. \copy3\par
     u3. \unhcopy3\par
     c4. \copy4\par
     u4. \unhcopy4\par
     u5. \unhcopy5\par
Produces: See typeset version.

Comments:

  • This example is the same as the one on the \unhbox reference page, except it uses \unhcopy instead of \unhbox.
TeXbook References: 120. Also: 120, 283, 285, 293, 353.

Related Primitives: unhbox, box, copy.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

unkern Kern
Command
Synopsis: \unkern

Description:

    IF the last item on the current list is a kern, \unkern removes it; otherwise \unkern has no effect. The command may not be used in vertical mode if the main vertical list-so-far has been entirely contributed to the current page [280].
Example:

     \ifdim\lastkern=0pt% test for kern
     \else
          \dimen1=\lastkern %store last kern in dimen1
          \unkern %remove kern from list
     \fi
Produces: See typeset version.

Comments:

  • This code fragment would normally be used in a macro which breaks a box into its basic components.
TeXbook References: 280. Also: 280.

Related Primitives: lastkern, unpenalty, unskip.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

unpenalty Penalties
Command
Synopsis: \unpenalty

Description:

    IF the last item on the current list is a penalty, \unpenalty removes it; otherwise \unpenalty has no effect. The command may not be used in vertical mode if the main vertical list-so-far has been entirely contributed to the current page [280].
Example:

     \ifnum\lastpenalty=0 %test for penalty.
     \else
          \count1=\lastpenalty %store last penalty in \count1
          \unpenalty %remove penalty from list
     \fi
Produces: See typeset version.

Comments:

  • This code fragment would normally be used in a macro which breaks a box into its basic components.
TeXbook References: 280. Also: 280.

Related Primitives: lastpenalty, unkern, unskip.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

unskip Glue
Command
Synopsis: \unskip

Description:

    IF the last item on the current list is glue, \unskip removes it; otherwise \unskip has no effect [222]. The command may not be used in vertical mode if the main vertical list-so-far has been entirely contributed to the current page [280]. However, \vskip-\lastskip has almost the same effect [223].
Example:

     \ifdim\lastskip=0pt %test for glue.
     \else
          \skip1=\lastskip %store last glue in \skip1.
          \unskip %remove glue from list
     \fi
Produces: See typeset version.

Comments:

  • This code fragment would normally be used in a macro which breaks a box into its basic components.
TeXbook References: 280. Also: 222-223, 280, 286, 313, 392, 418-419.

Related Primitives: lastskip, unkern, unpenalty.

For Additional Examples, see: afterassignment

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

unvbox Box
Command
Synopsis: \unvbox<8-bit register number>

Description:

    THIS command is similar to \box except it unsets glue at the box's outermost level [120]. Also, the box register must either contain a \vbox (or \vtop[nr]) or be empty. In vertical mode nothing happens if the register is empty, and the vertical list in the register is added without change to the current list if it is not. In particular, \prevdepth is not changed [282]. In horizontal mode \par is added to the current paragraph and then the vertical list in the vbox is added to the current list. The command is not allowed in restricted horizontal mode [286] or in math mode. After an \unvbox command the box register is empty [120].
Example:

  1. \setbox1=\vbox{\hsize=20pt\vrule height 5pt width 20pt depth 5pt}
  2. The (h, d, w) of box1 are: (\the\ht1, \the\dp1, \the\wd1).\par
  3. \def\makevbox#1#2#3%
  4. {%
  5.      \global\setbox#1=\vbox to 45pt
  6.      {
  7.           \offinterlineskip% see [352] in TTB.
  8.           \copy1\vskip 2pt plus#2
  9.           \copy1\vskip 2pt plus#3
 10.           \copy1
 11.      }
 12.      The (h, d, w) of box#1 are: (\the\ht#1, \the\dp#1, \the\wd#1).\par
 13. }
 14. \makevbox{2}{0pt}{0pt}
 15. \makevbox{3}{1pt}{4pt}
 16. \makevbox{4}{1fil}{1fil}
 17. \vskip 2pt
 18. \noindent
 19. \hbox{\boxit{\copy2}\kern20pt\boxit{\copy3}\kern20pt\boxit{\copy4}}
 20. \kern20pt
 21. \hbox{\boxit{\unvbox2}\kern20pt\boxit{\unvbox3}\kern20pt\boxit{\unvbox4}}
 22. \par\penalty10000\noindent
 23. \hbox to 140pt{Three boxes using |\copy|.\hfil} Three boxes using |\unvbox|.
Produces: See typeset version.

Comments:

  • The dimensions of boxes 1-4 are calculated using \boxmaxdepth=4pt.
  • The spacing in the three \copy boxes is due to the `to 45pt' on line 5 and to parameters 2 and 3 on lines 14-16. The extra space goes away in the three \unvbox boxes.
  • The \par on line 22 ends the paragraph begun by \noindent on line 18. The large penalty on line 22 tells TeX to keep the material made on lines 18-21 and the line made by line 23 on the same page.
TeXbook References: 120. Also: 120, 254, 282, 286, 354, 361, 363, 364, 392, 399, 417.

Related Primitives: unvcopy, box.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

unvcopy Box
Command
Synopsis: \unvcopy<8-bit register number>

Description:

    THIS command is similar to \copy except it unsets glue at the box's outermost level [120]. Also, the box register must either contain a \vbox (or \vtop[nr]) or be empty. In vertical mode nothing happens if the register is empty, and the vertical list in the register is added without change to the current list if it is not. In particular, \prevdepth is not changed [282]. In horizontal mode \par is added to the current paragraph and then the vertical list in the vbox is added to the current list. The command is not allowed in restricted horizontal mode [286] or in math mode. The box register is unchanged by an \unvcopy command [120].
Example:

  1. \setbox1=\vbox{\hsize=20pt\vrule height 5pt width 20pt depth 5pt}
  2. The (h, d, w) of box1 are: (\the\ht1, \the\dp1, \the\wd1).\par
  3. \def\makevbox#1#2#3%
  4. {%
  5.      \global\setbox#1=\vbox to 45pt
  6.      {
  7.           \offinterlineskip% see [352] in TTB.
  8.           \copy1\vskip 2pt plus#2
  9.           \copy1\vskip 2pt plus#3
 10.           \copy1
 11.      }
 12.      The (h, d, w) of box#1 are: (\the\ht#1, \the\dp#1, \the\wd#1).\par
 13. }
 14. \makevbox{2}{1pt}{1pt}
 15. \makevbox{3}{4pt}{1pt}
 16. \makevbox{4}{1fil}{1fil}
 17. \vskip 2pt
 18. \noindent
 19. \hbox{\boxit{\copy2}\kern20pt\boxit{\copy3}\kern20pt\boxit{\copy4}}
 20. \kern20pt
 21. \hbox{\boxit{\unvcopy2}\kern20pt\boxit{\unvcopy3}\kern20pt\boxit{\unvcopy4}}
 22. \par\penalty10000\noindent
 23. \hbox to 140pt{Three boxes using |\copy|.\hfil} Three boxes using |\unvcopy|.
Produces: See typeset version.

Comments:

  • This example is almost the same as the one on the \unvbox reference page, except it uses \unvcopy instead of \unvbox. Also, the skip values on lines 14-15 are different in the two examples.
TeXbook References: 120. Also: 120, 282, 286, 361.

Related Primitives: unvbox, box, copy.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

uppercase Character
Command
Synopsis: \uppercase{<token list>}

Description:

    THIS command converts every character in the token list to its \uccode value unless that value is zero in which case no change is made. The conversion is made in TeX's stomach [41]. Expansion is suppressed during the conversion [215]. Active characters (category 13) behave like character tokens and may be converted [307].
Example:

  1. \def\myname{David}
  2. \def\MYNAME{\uppercase{\myname}}
  3. \def\MYNAMEA{\uppercase\expandafter{\myname}}
  4. \myname---\MYNAME---\MYNAMEA\par
  5. \uccode`~=`X
  6. \catcode`X=13
  7. \def X{\char`Y}
  8. \def\myname{Dr.~David~Bausum}
  9. \myname---\MYNAME---\MYNAMEA\par
Produces: See typeset version.

Comments:

  • Line 2 makes it appear as if the second name on each line should be in uppercase. It is not because tokens which represent control sequences are usually not expanded inside \uppercase. Thus, \myname on line 2 is not expanded and hense not converted.
  • However, on line 3 \expandafter is expanded earlier than \uppercase. That allows \uppercase to see the characters in the replacement text for \myname.
  • Lines 8 and 9 show that \uppercase also works with active characters. However, the three things done in lines 5-7 are required. In particular, if either line 6 or 7 is omitted, TeX complains of an error.
TeXbook References: 41. Also: 41, 215, 217, 279, 307, 345, 348, 374, 377, 394.

Related Primitives: uccode, lowercase.

For Additional Examples, see: expandafter, uccode

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

vadjust Paragraph
Command
Synopsis: \vadjust{<vertical list>}

Description:

    THIS command provides a way to insert vertical material at a particular point in a paragraph without interfering with the rest of the paragraph. When formatting a paragraph containing \vadjust, TeX: a) saves the specified vertical list; b) breaks the paragraph into lines; c) adds the lines to the enclosing vertical list; and d) inserts the saved list into the enclosing vertical list immediately after the line which held the original \vadjust. For example, if `\vadjust{\eject}' is placed in a paragraph, a page break will occur at the end of the line containing the \vadjust. Also, the paragraph will continue as normal on the next page [105]. The command is not allowed in vertical modes [281].
Example:

  1. \def\strutA#1#2{\vrule height#1 depth#2 width0pt}
  2. \def\ta#1%
  3. {%
  4.      \strutA{8.5pt}{3.5pt}%
  5.      \vadjust
  6.      {
  7.           \vbox to 0pt
  8.           {
  9.                \kern-1\baselineskip
 10.                \moveleft0.5in\hbox to 0.5in
 11.                {
 12.                     \strutA{8.5pt}{3.5pt}%
 13.                     \hfil#1\kern1em
 14.                }
 15.                \vss
 16.           }%
 17.      }%
 18. }
 19. \hsize=4.75in
 20. There are cries, sobs, confusion among the people, and at that moment
 21. the cardinal himself, the Grand Inquisitor, passes by the cathedral.
 22. He is an old man, almost ninety, tall and erect,\ta{100} with a
 23. withered face and sunken eyes, in which there is still a gleam of
 24. light. He is not dressed in his brilliant cardinal's robes, as he was
 25. the day before, when he was burning the enemies of the Roman
 26. Church~\char144 \kern2em\hfill Fyodor Dostoyevsky, {\it The Brothers
 27. Karamazov}\par
Produces: See typeset version.

Comments:

  • This example shows one way to put material in the margin opposite a particular line. The struts made on lines 4 and 12 align the margin material with the line in the paragraph. The first strut is placed in the paragraph, and the second is in the margin material.
  • The \vadjust contains a \vbox whose height is zero and which contains two items: a kern which moves back 1 line, and a box which is moved left 0.5 inches.
TeXbook References: 105. Also: 95, 105, 109, 110, 117, 259, 281, 316, 393, 454.

Related Primitives: penalty.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

valign Tables
Command
Synopsis: \valign<box specification>{<alignment material>}

Description:

    THIS command is similar to \halign except rows and columns are interchanged. So, \cr separates columns; & separates rows in 1 column; and \noalign inserts horizontal mode material between columns (e.g., \vrule). Each individual entry in a column is placed in a vbox whose depth is 0pt. The heights of each row in a \valign are maximized, just as the widths of each column in an \halign are. The \span command now spans rows instead of columns [249].
Example:

  1. \def\strutA#1#2{\vrule height#1 depth#2 width0pt}
  2. \valign{&\hbox to 1in{\strutA{9pt}{3pt}#\hfil}\vfil\cr
  3. badness&box&boxmaxdepth&cleaders©&dp&everyhbox\cr
  4. everyvbox&hbadness&hbox&hfuzz&hrule&ht&lastbox\cr
  5. leaders&overfullrule&prevdepth&setbox&unhbox&unhcopy&unvbox\cr
  6. unvcopy&vbadness&vbox&vfuzz&vrule&vsplit&vtop\cr
  7. wd&xleaders\cr
  8. }
Produces: See typeset version.

Comments:

  • If only lines 3-7 are examined in the above example, there is no hint that those lines are part of a \valign instead of an \halign. However, when the actual table is viewed, it becomes clear that the words on a particular line (e.g., 4) appear in a particular column (e.g., 2).
  • Without the strut in the preamble, the interline spaceing in the table would be off. Also, the `\hbox to 1in' on line 2 limits the width of the vbox made for each entry. Since the normal width of a vbox is \hsize, the table won't fit on the page unless something special is done.
TeXbook References: 249. Also: 249, 283, 285-286, 302, 335, 397.

Related Primitives: cr, noalign, omit, span, tabskip, crcr, everycr, halign.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

vbadness Box
1000 * Parameter (integer)
Synopsis: \vbadness

Description:

    WHEN a \vbox or \vtop is made, the \badness of the box is compared to \vbadness [272]. If \badness is less than or equal to \vbadness, the box is acceptable. Otherwise, a message is written to the log file, and the box is considered: overfull, tight, loose, or underfull. The distinction between the four types of bad boxes depends on whether the glue in the box shrinks or stretches and on the parameters: \vbadness and \vfuzz. The following table [302] summarizes the possibilities:

    bad box type | glue | additional conditions
overfull | shrink | \vbadness < 100 or excess width > \vfuzz.
tight | shrink | (all other shrink cases)
loose | stretch | \vbadness < \badness <= 100.
underfull | stretch | (all other stretch cases)

TeXbook References: 272, 302. Also: 272, 348, 397, 417.

Related Primitives: vfuzz, badness, hbadness.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

vbox Box
Command
Synopsis: \vbox<box specification>{<vertical material>}

Description:

    THERE are three forms of \vbox: `\vbox {material}', `\vbox to <dimen> {material}', and `\vbox spread <dimen> {material}' [80]. The material inside a vbox is actually a vertical list make up of boxes, kerns, glue, and other dimensionless items (e.g., marks, penalties, and whatsits\mkindex{whatsit}). The depth of the vbox is zero, unless the last item on the vertical list is a box. If that box has depth d, then the depth of the vbox is min(d,\boxmaxdepth). The natural height h of a vbox is the sum of the heights and depths of all the boxes in the vertical list plus the sum of all the kern items in the list plus the sum of the rigid component of all glue items in the list minus d. For a \vbox without a to or spread component, the height of the box is just h. But, for a to vbox the height is the <dimen>, and for a spread vbox the height is h plus the <dimen>. The last two cases result in overfull or underfull boxes unless the glue in the box can shrink or expand to the actual height of the box. Only the boxes in the vertical list enter into the calculation of the width of a vbox. For each box in the list, which ends to the right of the vbox reference point, compute the distance from the reference point to the box's end. Take into account all \moveright and \moveleft commands that apply to the box. The width of the vbox is the maximum of the distances just computed (assuming the list contains at least one box meeting the restrictions) or it is zero [80-81]. Vboxes tend to have large heights and small depths in contrast to vtops which tend to have small heights and large depths [82]. A \vbox is indecomposable. TeX will not split it between two pages [93].
Example:

  1. \setbox0=\hbox{Here are }
  2. \setbox1=\hbox{two lines of text}
  3. \setbox2=\hbox{made by a vbox.}
  4. \setbox3=\vbox{\box1\box2}
  5. \hbox{\box0\box3}
Produces: See typeset version.

Comments:

  • The \vbox made on line 4 consists of two partial lines of text (i.e., boxes 1 and 2). Its baseline is the baseline from \box2.
  • The \hbox constructed on line 5 lines up the baselines of boxes 0 and 3.
  • Compare this example to the one on the \vtop reference page.
TeXbook References: 80-82, 278. Also: 65, 80-82, 103, 151, 193, 222, 278, 388-389.

Related Primitives: setbox, vtop, hbox, boxmaxdepth.

For Additional Examples, see: special, vskip, vss

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

vcenter Math (Box)
Command
Synopsis: \vcenter<box specification>{<vertical material>}

Description:

    EACH formula has an axis which is an invisible horizontal line that runs above the baseline [150]. The \vcenter command puts its material in a box (just as \vbox does) then it centers the box on the axis. The same three box specification used with \vbox may be used with \vcenter: none, `to <dimen>', and `spread <dimen>' [151]. Several Plain TeX macros are built using \vcenter and \halign: \cases, \eqalign, and \matrix. Material placed in a \vcenter will not be split between two pages. That is because TeX puts the material in a box, and TeX doesn't split boxes between pages [193].
Example:

  1. $$ f(x) = \left\{
  2.           \vcenter
  3.           {%
  4.                \halign
  5.                {%
  6.                     $#\hfil$&\quad #\hfil\cr
  7.                     x^2 + 2x - 1& if $x \le 0$,\cr
  8.                     x^3 - 1     & if $x > 0$.\cr% this . ends the sentence
  9.                }%
 10.           }%
 11.           \right.%this . is a null delimiter
 12. $$
 13. %$$f(x) = \left\{\vcenter{\halign{$#\hfil$&\quad #\hfil\cr
 14. %x^2 + 2x - 1& if $x \le 0$,\cr
 15. %x^3 - 1     & if $x > 0$.\cr}}\right.$$
Produces: See typeset version.

Comments:

  • Lines 1-12 illustrate a function which is defined in two parts. The construction requires four commands: \left with {; \right with a null delimiter; \vcenter; and \halign.
  • The material on line 1 outside the \vcenter sets up the axis for the display.
  • Lines 4-9 use \halign to build a table which is put in the \vcenter. This is were the main part of the definition is typeset.
  • Lines 13-15 (without the %'s) might be a more natural way to enter the function in a document, but the longer format shows more clearly how the construction is made.
TeXbook References: 150-151. Also: 150-151, 159, 170, 193, 222, 242, 290, 361, 443.

Related Primitives: vbox.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

vfil Glue
Derived Command
Synopsis: \vfil

Description:

    THIS command is essentially equivalent to: `\vskip 0pt plus 1fil' [72]. If \vfil appears in unrestricted horizontal mode, the current paragraph ends. It is not allowed in restricted horizontal mode [286]. It appends vertical glue to vertical lists [281]. It is used with \vfilneg in the Plain TeX macro \filbreak [111].
Example:

  1. \setbox0=\vbox to 1in{\hsize=2.5in Without the ending |\vfil| this box
  2. would be underfull!\vfil}
  3. \boxit{\box0}
Produces: See typeset version.

Comments:

  • The |'s surrounding \vfil on line 1 begin and end in-line verbatim mode.
TeXbook References: 71-72. Also: 71-72, 111, 256, 281, 286, 417.

Related Primitives: vskip, vfill, vfilneg, vss.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

vfill Glue
Derived Command
Synopsis: \vfill

Description:

    THIS command is essentially equivalent to: `\vskip 0pt plus 1fill' [72]. If \vfill appears in unrestricted horizontal mode, the current paragraph ends. It is not allowed in restricted horizontal mode [286]. It appends vertical glue to vertical lists [281]. It is often used to fill a page with white space just before an \eject [24].
Example:

  1. \vfill
  2. \eject
  3. \ifodd\pageno% Plain TeX doesn't have \ifeven
  4. \else
  5.      \trmpage{0}{1}
  6.      \hbox to 0pt{}% If \trmpage does nothing, this is required
  7.      \vfill%         for the eject to work.
  8.      \eject
  9. \fi
Produces: See typeset version.

Comments:

  • These lines might be used to finish a chapter in a book or an article in an academic journal. In either case the next chapter or article should begin on a recto page (i.e., a right-hand one with an odd page number).
  • Lines 1-2 fill out the last page and eject it.
  • Then, if the current page number is odd, nothing needs to be done (note, there is no \ifeven test). Otherwise, a second page needs to be ejected. Although that page will have a empty body, it may have a header and a footer, and either may be different from the normal one.
  • Line 5 sets up the proper header and footer (both may be blank), and line 6 makes TeX think the page holds something. Without line 6 the following \vfill\eject will have no effect.
TeXbook References: 71-72. Also: 24, 25, 71-72, 256-257, 281, 286.

Related Primitives: vskip, vfil.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

vfilneg Glue
Derived Command
Synopsis: \vfilneg

Description:

    THIS command is essentially equivalent to: `\vskip 0pt plus -1fil' [72]. If \vfilneg appears in unrestricted horizontal mode, the current paragraph ends. It is not allowed in restricted horizontal mode [286]. It appends vertical glue to vertical lists [281].
Example:

     \def\filbreak{\vfil\penalty-200\vfilneg}
Produces: See typeset version.

Comments:

  • Filbreak is a Plain Tex macro which means ``break the page here unless there is room for more text followed by \filbreak'' [111].
  • It might be used in a directory or other project with many small paragraphs none of which should be split between pages.
TeXbook References: 72. Also: 72, 111, 281, 286.

Related Primitives: vskip, vfil.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

vfuzz Box
0.1pt * Parameter (dimen)
Synopsis: \vfuzz

Description:

    TEX uses this parameter with \vbadness in classifying a \vbox or \vtop which contains more material than will fit even after the glue in the box has shrunk all it can. TeX considers the box overfull if the excess width of the box is larger than \vfuzz or \vbadness is less than 100 [302].
TeXbook References: 274, 302. Also: 274, 348.

Related Primitives: vbadness, hfuzz.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

voffset Page
0pt * Parameter (dimen)
Synopsis: \voffset=<dimen>

Description:

    THIS parameter controls the location of each typeset page's top margin. The default value of \voffset is 0pt, and TeX makes a 1-inch top margin. That margin is moved down if \voffset is given a positive dimension and up if it is given a negative dimension [251].
Example:

     \voffset=-0.7in
Produces: See typeset version.

Comments:

  • In contrast to \hoffset, which may require a different value on even and odd pages, \voffset rarely needs to be changed.
TeXbook References: 251. Also: 251-253, 274, 342, 406.

Related Primitives: hoffset, hsize, vsize.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

vrule Box
Command
Synopsis: \vrule[height<dimen> depth<dimen> width<dimen>]

Description:

    A rule box is a solid black rectangular box with a height, depth, and width. Such a box may look like a horizontal or vertical line. The \vrule command makes a rule box, but the command may only be used in horizontal mode. If none of the box dimensions are specified, the box has width 0.4pt, and its height and depth extend to the smallest box that encloses it. No glue is placed to the left or right of a \vrule [221]. If \vrule is used in vertical mode, a new paragraph is started, and the rule box is typeset [222]. However, a \vrule may be used with \leaders in vertical mode [224-225].
Example:

  1. Here is a square vrule: \vrule height 0.23in depth 0.02in width 0.25in\par
  2. \def\tvr#1#2#3{#1. Here is another type of vrule #2\ in a line.#3\par}
  3. \tvr A{\vrule width 1in}{}
  4. \tvr B{\vrule height 0.4pt width 1in}{}
  5. \tvr C{\vrule height 3.4pt depth -3pt width 1in}{}
  6. \tvr D{\vrule}{}% Note: Caslon's D is ~0.74pt wider than its E (at 10pt).
  7. \tvr E{\vrule}{\vrule height 8.5pt depth 3.5pt width 0pt} % Use a strut.
Produces: See typeset version.

Comments:

  • Line 1 typesets a square with quarter-inch sides.
  • Line 2 defines a macro which is used on lines 3-7 to typeset several types of vrules.
  • Lines 3 and 4 show how the height and depth of a vrule expand if neither is specified.
  • Line 5 shows how a negative depth in a vrule works.
  • Line 6 shows that if no dimensions are specified for a vrule, TeX makes a vertical rule.
  • Finally, the third parameter on line 7 acts as a strut which increases the height and depth of the line. That explains why the rule made by the second parameter on line 7 is larger than the rule made by line 6.
TeXbook References: 221-224. Also: 64, 86, 151, 221-222, 224, 245-247, 281-282, 283, 357, 392, 420.

Related Primitives: hrule, leaders.

For Additional Examples, see: crcr, everycr, halign, vadjust

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

vsize Page
8.9in * Parameter (dimen)
Synopsis: \vsize=<dimen>

Description:

    EACH page TeX typesets normally contains a header, footer, and page body, but any of the three may be omitted. The height of the body is \vsize [255]. TeX places the body in \box255 where the output routine adds an appropriate header and footer and performs other tasks [253]. TeX stores the value of \vsize in \pagegoal when the first box or insertion is put on a new page. Changes to \vsize are not reflected until a new page is started [114]. Increasing \vsize is often one step in mixing single and double column output [417]. In The TeXbook the word page generally means the page body. In fact, Chapter 15 of The TeXbook is entitled ``How TeX Makes Lines into Pages,'' and it is really the page body that is ``made out of lines'' [nr].
Example:

  1. \begingroup
  2.      \output={\global\setbox\partialpage=\vbox{\unvbox255}}
  3.      \eject
  4.      \output={\doublecolumnoutA}
  5.      \hsize=\pagewidthB
  6.      \vsize=\pageheightB
  7.      \advance \vsize by -\ht\partialpage
  8.      \multiply \vsize by2
  9.      . . .
Produces: See typeset version.

Comments:

  • The above lines begin a routine which prepares double column output.
  • Such a routine redefines many basic items. So, everything is done in a group.
  • Line 2-3 move everything on the current page to a temporary box. Thus, all future additions will be to a new page.
  • Lines 6-8 compute a new value for \vsize. When the first box or insertion is added to the new page, \pagegoal is reinitialized to the new \vsize.
TeXbook References: 113-114, 251. Also: 113-114, 251, 253, 255, 274, 340-341, 348, 400, 406, 413, 415, 417.

Related Primitives: pagegoal, maxdepth, hsize, hoffset, voffset.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

vskip Glue
Command
Synopsis: \vskip<glue>

Description:

    THIS command inserts glue in vertical mode. It is used with fil and fill to make \vfil and \vfill. Although filll exists, \vfilll is not a primitive [72]. If \vskip appears in unrestricted horizontal mode, the current paragraph ends. It is not allowed in restricted horizontal mode [286].
Example:

     \hsize=2in
     \def\tcenterline#1{\hbox to \hsize{\hfil #1\hfil}}
     \moveright1.5in\vbox to 1in
     {%
          \hrule
          \vskip 6pt plus 6pt minus 3pt
          \tcenterline{The Name of the Game}
          \vskip 6pt plus 6pt minus 3pt
          \tcenterline{is}
          \vskip 6pt plus 6pt minus 3pt
          \tcenterline{\it A Good Question}
          \vskip 6pt plus 6pt minus 3pt
          \hrule
     }
Produces: See typeset version.

Comments:

  • The above vbox does not give an underfull warning. However, if `plus 6 pt' is changed to `plus 1pt' or each \vskip line is changed to `\kern 6pt' then the vbox is underfull.
TeXbook References: 71-72. Also: 24, 71, 85, 191, 281, 286.

Related Primitives: vfil, vfill, vfilneg, vss, hskip, kern.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

vsplit Inserts (Box)
Command
Synopsis: \vsplit<8-bit register number> to <dimen>

Description:

    THE command `\setbox m=\vsplit n to <dimen>' splits a box into two pieces. The original box (i.e., \box n) should be a vbox and hold a vertical list. The maximum depth of the new box (i.e., \box m) is \splitmaxdepth. After the breakpoint in \box n is determined, items in the list are moved to \box m. Next, the same items are removed from \box n. Also, all discardable items immediately following the breakpoint are removed from \box n. Finally, the glue specified by \splittopskip is added to the top of \box n [124].
TeXbook References: 124. Also: 124, 222, 259, 278, 397, 417.

Related Primitives: splitmaxdepth, splittopskip, splitbotmark, splitfirstmark, insert.

For Additional Examples, see: splittopskip

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

vss Glue
Derived Command
Synopsis: \vss

Description:

    THIS command is essentially equivalent to: `\vskip 0pt plus 1fil minus 1fil' [72]. If \vss appears in unrestricted horizontal mode, the current paragraph ends. It is not allowed in restricted horizontal mode [286]. It appends vertical glue to vertical lists [281].
Example:

  1. \def\thcropmark(#1,#2)% (horizontal,vertical) offsets.
  2. {%
  3.      \vbox to 0pt
  4.      {%
  5.           \kern #2in
  6.           \hbox
  7.           {%
  8.                \kern #1in
  9.                \vrule height 0.1pt width 0.1in
 10.           }%
 11.           \vss% \vss is often used in a \vbox to 0pt{}.
 12.      }%
 13.      \nointerlineskip
 14. }
 15. \thcropmark(0.1,0.3)%upper left - ODD page
 16. \tvcropmark(0.3,0.1)
 17. \thcropmark(1.3,0.3)%upper right
 18. \tvcropmark(1.2,0.1)
 19. \thcropmark(0.1,1.7)%lower left
 20. \tvcropmark(0.3,1.8)
 21. \thcropmark(1.3,1.7)%lower right
 22. \tvcropmark(1.2,1.8)
 23. \setbox0=\vbox to 2in{\hbox to 1.545in{\hfill}\vfill}
 24. \boxitA{\box0}{}
Produces: See typeset version.

Comments:

  • This example illustrates one way to produce crop marks. Two special macros are required: one for the horizontal lines and one for the vertical lines.
  • Lines 1-14 show the macro used to print horizontal lines. The macro is deceptively simple. It requires a horizontal and vertical offset from the upper left-hand corner of the box representing a page, and it add two things to the current list: a vbox (lines 3-12) and the suppression of interline glue normally placed between boxes (line 13). The vbox in turn contains three things: a kern which moves down the page since it is in vertical mode; an hbox; and glue which is infinitely stretchable and shrinkable. Since the vbox has height 0, the glue will shrink. Finally, the hbox contains a kern which moves right since it is in horizontal mode and a vrule which makes a thin line .1 inch long. The \tvcropmark macro is identical except it makes a thin line .1 inch tall (i.e., its line 9 is: `\vrule height 0.1in width 0.1pt').
  • Collectively, lines 15-22 add 8 boxes which are not separated by interline glue to the current list. Since each box has 0 height and depth, the boxes' contents are displayed on top of each other.
  • Finally, line 23 makes an empty box scaled down from 8.5 by 11 inches, and line 24 prints that box with lines around it. On line 23, \hfil or \hss could have been used instead of \hfill and a similar substitution could have been made for \vfill.
TeXbook References: 71-72. Also: 71- 72, 255, 281, 286.

Related Primitives: vskip, vfil.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

vtop Box
Command
Synopsis: \vtop<box specification>{<vertical material>}

Description:

    THERE are three forms of \vtop: `\vtop {material}', `\vtop to <dimen> {material}', and `\vtop spread <dimen> {material}'. The material inside a vtop is actually a vertical list make up of boxes, kerns, glue, and other dimensionless items (e.g., marks, penalties, and whatsits\mkindex{whatsit}). In order to compute the dimensions of the vtop, first put the vertical list inside a \vbox (with the same box specifications) and compute the vbox's height, depth, and width (h, d, w). Next, set x equal to zero unless the first item on the list is a box. In that case set x equal to the height of the box. Finally, the height, depth, and width of the desired \vtop are: x, h + d - x, and w [81]. Vtops tend to have large depths and small heights in contrast to vboxes which tend to have small depths and large heights [82]. A \vtop is indecomposable. TeX will not split it between two pages [93].
Example:

  1. \setbox0=\hbox{Here are }
  2. \setbox1=\hbox{two lines of text}
  3. \setbox2=\hbox{made by a vtop.}
  4. \setbox3=\vtop{\box1\box2}
  5. \hbox{\box0\box3}
Produces: See typeset version.

Comments:

  • The \vtop made on line 4 consists of two partial lines of text (i.e., boxes 1 and 2). Its baseline is the baseline from \box1.
  • The \hbox constructed on line 5 lines up the baselines of boxes 0 and 3.
  • Compare this example to the one on the \vbox reference page.
TeXbook References: 81-82, 278. Also: 81-82, 151, 222, 278, 333.

Related Primitives: setbox, vbox, hbox.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

wd Box
Internal Quantity
Synopsis: \wd<8-bit register number>

Description:

    EVERY box has a width which is a <dimen> quantity. When material is placed in a box, the width of the box is automatically recomputed. The width may be accessed or changed using \wd<number> [120].
Example:

  1. \setbox0=\hbox{Every box has }
  2. \setbox1=\hbox{a }
  3. The width of box 0 is \the\wd0.\par
  4. The width of box 1 is \the\wd1.\par
  5. \hbox{\box0\copy1 width}
  6. The width of box 0 is \the\wd0.\par
  7. The width of box 1 is \the\wd1.\par
Produces: See typeset version.

Comments:

  • Initially, both boxes have a positive width. Line 5 empties \box0, and its width becomes 0.
TeXbook References: 120. Also: 120, 271, 388-389, 391, 417.

Related Primitives: dp, ht, setbox.

For Additional Examples, see: boxmaxdepth

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

widowpenalty Penalties (Page)
150 * Parameter (integer)
Synopsis: \widowpenalty

Description:

    AFTER TeX breaks a paragraph into lines, it moves each line to the containing vertical list. Normally, TeX places a penalty followed by interline glue between each pair of lines. TeX adds \widowpenalty to the penalties inserted immediately after the penultimate line in the paragraph [104].
TeXbook References: 104. Also: 104, 113, 272, 348.

Related Primitives: clubpenalty, brokenpenalty, interlinepenalty.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

write File I/O
Command
Synopsis: \write<number>{<token list>}

Description:

    THIS command writes one or more lines to a file or the terminal. If <number> corresponds to a file opened by \openout that is not yet closed, the output goes to that file. Otherwise, the output is written to the log file and, if number is non-negative, to the terminal [226]. Unless \immediate preceeds \write, TeX puts the command in a whatsit\mkindex{whatsit`5`file I/O} item in the current list. Then, the write takes place later during any \shipout which applies to the list [227]. The token list is expanded when it is actually written to the file not when it is placed in the whatsit [215]. However, tokens in the list preceeded by \noexpand are not expanded [377]. The token list should contain the same number of left and right braces [280]. TeX puts a newline character at the end of every \write command. TeX ignores the command if it appears in a box governed by leaders [228].
Example:

  1. \def\tmklabel#1#2%
  2. {%
  3.      \write\twaux
  4.      {%
  5.           \noexpand\def
  6.           \expandafter\noexpand
  7.           \csname #1\endcsname{#2}%
  8.      }%
  9. }
 10. \tmklabel{junkA}{\the\pageno}
Produces: See typeset version.

Comments:

  • Line 10 in conjunction with lines 1-9 writes the line `\def \junkA {nnn}' to the file corresponding to \twaux. The actual number in {}'s will be the number of the page on which line 10 appears.
  • If the same file is input at the start of document, the control sequence \junkA will be defined and so may be used at any place where the page number for \junkA needs to be typeset.
TeXbook References: 226-228. Also: 215, 216, 226-228, 254, 280, 346, 377, 422, 424.

Related Primitives: immediate, openout, closeout.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

xdef Macro
Derived Command
Synopsis: \xdef<control sequence><parameter text>{<replacement text>}

Description:

    THIS command is equivalent to \global\edef [215]. The \global, \long, and \outer prefixes can be applied to \xdef in any order, and they can appear more than once [275].
Example:

  1. \def\ta{Bye\tc Bye}
  2. \def\tc{\hskip10pt}
  3. \edef\tb{Bye\tc Bye}
  4. 1. \ta\tb.\par
  5. \begingroup
  6. \def\ta{Hello\tc World}
  7. \xdef\tb{How are\tc you?}
  8. \def\tc{\hskip20pt}
  9. 2. \ta\tb.\par
 10. \endgroup
 11. 3. \ta\tb.\par
Produces: See typeset version.

Comments:

  • Lines 1-4 define and typeset two macros which use a common third macro.
  • Lines 5-10 hold a new group and contain new definitions for each of the macros. The \tb macro, originally defined using \edef, is redefined using \xdef.
  • Line 11 typesets the macros a third time. The \ta macro is the same on lines 4 and 11, but the global change made to \tb inside the group on line 7 continues after the group ends.
  • The original definition of \ta on line 1 uses \tc which is not defined until line 2. But, if lines 2 and 3 are switched (so \tc is also defined after \tb), TeX generates a run-time error and complains about an undefined control sequence in the definition of \tb. This is not a problem on line 7, where the new \tc follows both \ta and \tb, since \tb just uses the current version of \tc. In fact, the line 7 \tb uses the line 2 \tc.
TeXbook References: 215-216, 275, 373, 418, 424.

Related Primitives: edef, global, long, outer.

For Additional Examples, see: csname

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

xleaders Box
Command
Synopsis: \xleaders<box or rule><glue>

Description:

    LEADERS are used to fill space with a box or a rule. Normally, copies of a box will not completely fill a specified space. So, in addition to \leaders, TeX provides two additional ways to put boxes in the space. The first is \cleaders. It packs boxes tightly together and centers them in the specified space. The second is \xleaders. It breaks the leftover space into equal pieces and puts one piece between each box and on the left and right ends of the boxes. The result is a sbsb\ \char144\ sbs pattern where s stands for one of the pieces of space and b for one of the boxes [224].
Example:

  1. \def\sampletocC#1#2#3%
  2. {%
  3.      \bgroup
  4.           \setbox0=\hbox to 25pt{\vrule height 0.4pt depth 0pt width 25pt}
  5.           \def\tpage##1{\hbox to 25pt{\vrule\hfil ##1}}%
  6.           \setbox1=\hbox to 25pt{\vrule\hfil page}%
  7.           \hsize=224pt
  8.           \parindent=0pt
  9.           #1\leaders\copy0\hfill\tpage l\par
 10.           #2\leaders\copy0\hfill\tpage l\par
 11.           #3\leaders\copy0\hfill\tpage l\par
 12.           #1\cleaders\copy0\hfill\tpage c\par
 13.           #2\cleaders\copy0\hfill\tpage c\par
 14.           #3\cleaders\copy0\hfill\tpage c\par
 15.           #1\xleaders\copy0\hfill\tpage x\par
 16.           #2\xleaders\copy0\hfill\tpage x\par
 17.           #3\xleaders\copy0\hfill\tpage x\par
 18.      \egroup
 19. }
 20. \sampletocC{\noindent}{Strangers and Brothers}{The Age of Reason}
Produces: See typeset version.

Comments:

  • The `l', `c', or `x' at the right margin of each line shows whether the line was made by \leaders, \cleaders, or \xleaders.
  • Line 5 uses `##1' for the first parameter instead of `#1' because `\def\tpage' occurs inside a definition.
TeXbook References: 224. Also: 224.

Related Primitives: cleaders, leaders.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

xspaceskip Paragraph
0pt * Parameter (glue)
Synopsis: \xspaceskip=<glue>

Description:

    THERE are two ways to control interword spacing. The normal way uses \spacefactor f; the alternate way uses \spaceskip and \xspaceskip. If \xspaceskip is nonzero and f >= 2000, the \xspaceskip glue becomes the interword glue. Otherwise, if \spaceskip is nonzero, the \spaceskip glue has its stretch and shrink components multiplied by f/1000 and 1000/f, and that becomes the interword glue [76].
Example:

     \sfcode`\.3000\sfcode`\?3000\sfcode`\!3000%
      \sfcode`\:2000\sfcode`\;1500\sfcode`\,1250
     \xspaceskip=1.0em
     \spaceskip=0pt
     \tstory\par% The \adjdemerits reference page holds the definition of \tstory
     \xspaceskip=1.0em
     \spaceskip=0.5em
     \tstory\par
Produces: See typeset version.

Comments:

  • The first paragraph has a nonzero \xspaceskip and a zero spaceskip. The \spacefactor is used for the interword spaces except when f >= 2000 (e.g., between sentences). The result is justified lines with extra space between sentences.
  • The second paragraph uses one value between the words in a sentence and a second value between sentences. The result is unjustifed lines and underfull boxes.
TeXbook References: 76. Also: 76, 274, 317, 356, 429, 433.

Related Primitives: spaceskip, spacefactor.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

year Job
Parameter (integer)
Synopsis: \year

Description:

    At the beginning of each job TeX sets this parameter to the current year (e.g., 2000) [349].
Example:

  1. \def\ckleapyear#1% check if #1 is a leap year.
  2. {%
  3.   {%
  4.      \def\tleapy{not }% Most years fail.
  5.      \count10=#1
  6.      \count1=#1
  7.      \divide\count1 by 4
  8.      \multiply\count1 by 4
  9.      \ifnum\count1=\count10 % Worrry about 100 & 400.
 10.           \count2=#1
 11.           \divide\count2 by 100
 12.           \multiply\count2 by 100
 13.           \ifnum\count2=\count10 % Not a leap year unless 400 also divides.
 14.                \count3=#1
 15.                \divide\count3 by 400
 16.                \multiply\count3 by 400
 17.                \ifnum\count3=\count10
 18.                     \def\tleapy{}% Special leap year.
 19.                \fi
 20.           \else
 21.                \def\tleapy{}% This gets regular leap years.
 22.           \fi
 23.      \fi
 24.      The year #1 is \tleapy a leap year.\par
 25.   }%
 26. }
 27. \ckleapyear{1900}
 28. \ckleapyear{1990}
 29. \ckleapyear{1996}
 30. \ckleapyear{2000}
 31. \ckleapyear{2004}
 32. \ckleapyear{\the\year}
Produces: See typeset version.

Comments:

  • The macro in this example checks if a year is a leap year.
  • All the macro does is print one line (prepared on line 24), but it would be easy to adjust the macro to set a switch which could be referred to outside the macro.
  • Most years are not leap years, so \tleapy is set to `not ' on line 4. Then, the year is tested. If it is divisible by 4, but not by 100 (unless it is also divisible by 400), it is a leap year, and \tleapy is cleared (lines 18 and 21).
TeXbook References: 41, 349. Also: 41, 273, 349, 406.

Related Primitives: day, month, time.

For Additional Examples, see: expandafter

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.

TRM, Acknowledgment, Errors, Copyright, and Contacting
(Version: 0.707c. Prepared on: 4/ 1/2006 at: 13:54)
(Alphabetical Order) (Family Order)

TRM:
This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers.

Acknowledgment:
First: This material could not exist without Donald E. Knuth's work on TeX and his books: The TeXbook and TeX: The Program. My version of TeX includes the source files for both books, and I've poked around in both files trying to understand how TeX works.

Thank you, DEK.

Second: Each primitive's reference page contains a TeXbook Reference section which lists page numbers in The TeXbook for the primitive. The page numbers began as the primitive's index entry in The TeXbook. I removed the special formatting used in the index and consolidated page numbers. I added additional references for some primitives when I found a useful reference on a page which was not in the original index. For a few primitives I removed a page reference because I could not find the primitive on the page. Finally, for each primitive I picked one or two pages which seem to me most helpful in explaining how the primitive works. If you want to read in The TeXbook about a particular primitive, those page are a good place to start.

Third: The Description section on each primitive's reference page contains a number of statements which explain what the primitive does. Each statement concludes with a page reference to The TeXbook where more details may be available. For each primitive I read all appropriate page references, tried to get a global understanding of how the primitive works, and then summarized that understanding in as few words as possible keeping my comments in sync with page references to The TeXbook. BUT In some places my summary runs close to the original; in other places I've borrowered phrases or clauses from the original; and in a few places I've lifted a sentence or two from the original.

Errors:
If you find typos, minor mistakes, or major blunders in this file please send me a precise description of the problem, and I will fix things. This material exists in a pre-HTML, pre-TeX format. I run it through a custom program which makes tex and HTML files. The program uses a translation table to convert characters which have special TeX and HTML forms. I've proofread the typeset version of the tex files, but it's possible for a special character to appear correctly in typeset material but to display incorrectly and vice-versa.

If you have suggestions for improving the material, please send me your ideas, and I will consider them. I have intentionally not implemented the HTML version of the reference pages using frames. Note: my experiments show that it takes at most three mouse clicks to move between any two reference pages. Also, I am working on a 21-inch monitor which displays the equivalent of one typeset page at a time. The large monitor may distort my view of how easy it is to navigate through this material.

Copyright:
This HTML file is copyrighted, but it may be freely circulated provided it is: a) unchanged and b) free. If you wish to put it on a CD-Rom which is sold or distribute it in another form for a fee, please contact me in advance.

This is the HTML version of TeX Reference Manual by David Bausum. © Copyright 2002, Kluwer Academic Publishers. All Rights Reserved.