diff options
Diffstat (limited to 'info/texbytopic/TeXbyTopic.tex')
| -rw-r--r-- | info/texbytopic/TeXbyTopic.tex | 19044 |
1 files changed, 19044 insertions, 0 deletions
diff --git a/info/texbytopic/TeXbyTopic.tex b/info/texbytopic/TeXbyTopic.tex new file mode 100644 index 0000000000..00152621b2 --- /dev/null +++ b/info/texbytopic/TeXbyTopic.tex @@ -0,0 +1,19044 @@ +\documentclass[twoside,letterpaper]{rapport3} + +%\nofiles + +\usepackage{comment,makeidx} + +\usepackage{times} +\renewcommand{\ttdefault}{cmtt} + +\usepackage[plainpages=true,pagebackref=true]{hyperref} + +\usepackage{german} +% german +\righthyphenmin=3 +\mdqoff +\captionsenglish +\makeindex + +\usepackage{fancyhdr} +% headers & footers +\pagestyle{fancy} +% foot +\lfoot[\thepage]{\protect\small\protect\it Victor Eijkhout -- \protect\TeX\ by Topic} +\rfoot[{\protect\small\protect\it Victor Eijkhout -- \protect\TeX\ by Topic}]{\thepage} +\cfoot{} +% head +\lhead[\let\\\relax \let\uppercase\relax \leftmark]{\relax} +\chead{} +\rhead[\relax]{\let\\\relax \let\uppercase\relax \rightmark} + +\newdimen\tempdima \newdimen\tempdimb + +% these are fine +\def\nl{\protect\\}\def\n#1{{\tt #1}}\def\cs#1{{\tt\char`\\#1}}\let\csc\cs +\def\lb{{\tt\char`\{}}\def\rb{{\tt\char`\}}} +\def\gr#1{$\langle$#1$\rangle$}\def\key#1{{\tt#1}} +\def\alt{}\def\altt{}%this way in manstijl +\def\ldash{\unskip\ --\nobreak\ \ignorespaces} +\def\rdash{\unskip\nobreak\ --\ \ignorespaces} +% check these +\def\hex{{\tt"}} +\def\ascii{{\sc ascii}} +\def\ebcdic{{\sc ebcdic}} +\def\IniTeX{Ini\TeX}\def\LamsTeX{LAMS\TeX}\def\VirTeX{Vir\TeX} +\def\AmsTeX{Ams\TeX} +\def\TeXbook{the \TeX\ book}\def\web{{\sc web}} +% needs major thinking +\newenvironment{disp}{\begin{quotation}}{\end{quotation}} +\newenvironment{Disp}{\begin{quotation}}{\end{quotation}} +\newenvironment{tdisp}{\begin{quotation}}{\end{quotation}} +\newenvironment{example}{\begin{quotation}}{\end{quotation}} +\newenvironment{inventory}{\begin{description}}{\end{description}} +\newenvironment{glossinventory}{\begin{description}}{\end{description}} +\def\gram#1{\gr{#1}}%??? +% +% index +% +\def\term#1\par{\index{#1}} +\def\howto#1\par{} +\def\cstoidx#1\par{\index{#1@\cs{#1}@}} +\def\csterm#1\par{\cstoidx #1\par\cs{#1}} +\def\csidx#1{\cstoidx #1\par\cs{#1}} + +\begin{document} + +\def\tmc{\tracingmacros=2 \tracingcommands\tracingmacros} + +%%%%%%%%%%%%%%%%%%% +\makeatletter +\def\snugbox{\hbox\bgroup\setbox\z@\vbox\bgroup + \leftskip\z@ + \bgroup\aftergroup\make@snug + \let\next=} +\def\make@snug{\par\sn@gify\egroup \box\z@\egroup} +\def\sn@gify + {\skip\z@=\lastskip \unskip + \advance\skip\z@\lastskip \unskip + \unpenalty + \setbox\z@\lastbox + \ifvoid\z@ \nointerlineskip \else {\sn@gify} \fi + \hbox{\unhbox\z@}\nointerlineskip + \vskip\skip\z@ + } + +\def\figfont{\SansSerif \PointSize:8 \Style:roman } + +\newdimen\fbh \fbh=60pt % dimension for easy scaling: +\newdimen\fbw \fbw=60pt % height and width of character box + +\newdimen\dh \newdimen\dw % height and width of current character box +\newdimen\lh % height of previous character box +\newdimen\lw \lw=.4pt % line weight, instead of default .4pt + +\def\hdotfill{\noindent + \leaders\hbox{\vrule width 1pt height\lw + \kern4pt + \vrule width.5pt height\lw}\hfill\hbox{} + \par} +\def\hlinefill{\noindent + \leaders\hbox{\vrule width 5.5pt height\lw }\hfill\hbox{} + \par} +\def\stippel{$\qquad\qquad\qquad\qquad$} +\makeatother +%%%%%%%%%%%%%%%%%%% + +\begin{comment} +\def\SansSerif{\Typeface:macHelvetica } +\def\SerifFont{\Typeface:macTimes } +\def\SansSerif{\Typeface:bsGillSans } +\def\SerifFont{\Typeface:bsBaskerville } +\end{comment} +\let\SansSerif\relax \def\italic{\it} +\let\SerifFont\relax \def\MainFont{\rm} +\let\SansSerif\relax +\let\SerifFont\relax +\let\PopIndentLevel\relax \let\PushIndentLevel\relax +\let\ToVerso\relax \let\ToRecto\relax + +\begin{comment} +\def\stop@command@suffix{stop} +\let\PopListLevel\PopIndentLevel +\let\FlushRight\relax +\let\flushright\FlushRight +\let\SetListIndent\LevelIndent +\def\awp{\ifhmode\vadjust{\penalty-10000 }\else + \penalty-10000 \fi} +\end{comment} +\let\awp\relax +\let\PopIndentLevel\relax \let\PopListLevel\relax + +\showboxdepth=-1 + +\def\endofchapter{\vfill\noindent} + +\title{\TeX\ by Topic, A \TeX nician's Reference} +\date{} +\author{Victor Eijkhout} +\maketitle + \begin{minipage}[h]{1.0\linewidth} + Copyright \copyright\ 2007 Victor Eijkhout.\\ + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.2 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover + Texts. A copy of the license is included in the section entitled "GNU + Free Documentation License". +\medskip +This document is based on the book \TeX\ by Topic, +copyright 1991-2007 Victor Eijkhout. This book was +printed in~1991 by Addison-Wesley UK, ISBN 0-201-56882-9, reprinted +in~1993, pdf version first made freely available in~2001. + \end{minipage} + +\tableofcontents + +\pagebreak +\addcontentsline{toc}{section}{License} +\paragraph*{\bf License} +GNU Free Documentation License + +Version 1.2, November 2002 + + Copyright \copyright\ 2000,2001,2002 Free Software Foundation, Inc. + 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + +0. PREAMBLE + +The purpose of this License is to make a manual, textbook, or other +functional and useful document "free" in the sense of freedom: to +assure everyone the effective freedom to copy and redistribute it, +with or without modifying it, either commercially or noncommercially. +Secondarily, this License preserves for the author and publisher a way +to get credit for their work, while not being considered responsible +for modifications made by others. + +This License is a kind of "copyleft", which means that derivative +works of the document must themselves be free in the same sense. It +complements the GNU General Public License, which is a copyleft +license designed for free software. + +We have designed this License in order to use it for manuals for free +software, because free software needs free documentation: a free +program should come with manuals providing the same freedoms that the +software does. But this License is not limited to software manuals; it +can be used for any textual work, regardless of subject matter or +whether it is published as a printed book. We recommend this License +principally for works whose purpose is instruction or reference. + +1. APPLICABILITY AND DEFINITIONS + +This License applies to any manual or other work, in any medium, that +contains a notice placed by the copyright holder saying it can be +distributed under the terms of this License. Such a notice grants a +world-wide, royalty-free license, unlimited in duration, to use that +work under the conditions stated herein. The "Document", below, refers +to any such manual or work. Any member of the public is a licensee, +and is addressed as "you". You accept the license if you copy, modify +or distribute the work in a way requiring permission under copyright +law. + +A "Modified Version" of the Document means any work containing the +Document or a portion of it, either copied verbatim, or with +modifications and/or translated into another language. + +A "Secondary Section" is a named appendix or a front-matter section of +the Document that deals exclusively with the relationship of the +publishers or authors of the Document to the Document's overall +subject (or to related matters) and contains nothing that could fall +directly within that overall subject. (Thus, if the Document is in +part a textbook of mathematics, a Secondary Section may not explain +any mathematics.) The relationship could be a matter of historical +connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding +them. + +The "Invariant Sections" are certain Secondary Sections whose titles +are designated, as being those of Invariant Sections, in the notice +that says that the Document is released under this License. If a +section does not fit the above definition of Secondary then it is not +allowed to be designated as Invariant. The Document may contain zero +Invariant Sections. If the Document does not identify any Invariant +Sections then there are none. + +The "Cover Texts" are certain short passages of text that are listed, +as Front-Cover Texts or Back-Cover Texts, in the notice that says that +the Document is released under this License. A Front-Cover Text may be +at most 5 words, and a Back-Cover Text may be at most 25 words. + +A "Transparent" copy of the Document means a machine-readable copy, +represented in a format whose specification is available to the +general public, that is suitable for revising the document +straightforwardly with generic text editors or (for images composed of +pixels) generic paint programs or (for drawings) some widely available +drawing editor, and that is suitable for input to text formatters or +for automatic translation to a variety of formats suitable for input +to text formatters. A copy made in an otherwise Transparent file +format whose markup, or absence of markup, has been arranged to thwart +or discourage subsequent modification by readers is not Transparent. +An image format is not Transparent if used for any substantial amount +of text. A copy that is not "Transparent" is called "Opaque". + +Examples of suitable formats for Transparent copies include plain +ASCII without markup, Texinfo input format, LaTeX input format, SGML +or XML using a publicly available DTD, and standard-conforming simple +HTML, PostScript or PDF designed for human modification. Examples of +transparent image formats include PNG, XCF and JPG. Opaque formats +include proprietary formats that can be read and edited only by +proprietary word processors, SGML or XML for which the DTD and/or +processing tools are not generally available, and the +machine-generated HTML, PostScript or PDF produced by some word +processors for output purposes only. + +The "Title Page" means, for a printed book, the title page itself, +plus such following pages as are needed to hold, legibly, the material +this License requires to appear in the title page. For works in +formats which do not have any title page as such, "Title Page" means +the text near the most prominent appearance of the work's title, +preceding the beginning of the body of the text. + +A section "Entitled XYZ" means a named subunit of the Document whose +title either is precisely XYZ or contains XYZ in parentheses following +text that translates XYZ in another language. (Here XYZ stands for a +specific section name mentioned below, such as "Acknowledgements", +"Dedications", "Endorsements", or "History".) To "Preserve the Title" +of such a section when you modify the Document means that it remains a +section "Entitled XYZ" according to this definition. + +The Document may include Warranty Disclaimers next to the notice which +states that this License applies to the Document. These Warranty +Disclaimers are considered to be included by reference in this +License, but only as regards disclaiming warranties: any other +implication that these Warranty Disclaimers may have is void and has +no effect on the meaning of this License. + +2. VERBATIM COPYING + +You may copy and distribute the Document in any medium, either +commercially or noncommercially, provided that this License, the +copyright notices, and the license notice saying this License applies +to the Document are reproduced in all copies, and that you add no +other conditions whatsoever to those of this License. You may not use +technical measures to obstruct or control the reading or further +copying of the copies you make or distribute. However, you may accept +compensation in exchange for copies. If you distribute a large enough +number of copies you must also follow the conditions in section 3. + +You may also lend copies, under the same conditions stated above, and +you may publicly display copies. + +3. COPYING IN QUANTITY + +If you publish printed copies (or copies in media that commonly have +printed covers) of the Document, numbering more than 100, and the +Document's license notice requires Cover Texts, you must enclose the +copies in covers that carry, clearly and legibly, all these Cover +Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on +the back cover. Both covers must also clearly and legibly identify you +as the publisher of these copies. The front cover must present the +full title with all words of the title equally prominent and visible. +You may add other material on the covers in addition. Copying with +changes limited to the covers, as long as they preserve the title of +the Document and satisfy these conditions, can be treated as verbatim +copying in other respects. + +If the required texts for either cover are too voluminous to fit +legibly, you should put the first ones listed (as many as fit +reasonably) on the actual cover, and continue the rest onto adjacent +pages. + +If you publish or distribute Opaque copies of the Document numbering +more than 100, you must either include a machine-readable Transparent +copy along with each Opaque copy, or state in or with each Opaque copy +a computer-network location from which the general network-using +public has access to download using public-standard network protocols +a complete Transparent copy of the Document, free of added material. +If you use the latter option, you must take reasonably prudent steps, +when you begin distribution of Opaque copies in quantity, to ensure +that this Transparent copy will remain thus accessible at the stated +location until at least one year after the last time you distribute an +Opaque copy (directly or through your agents or retailers) of that +edition to the public. + +It is requested, but not required, that you contact the authors of the +Document well before redistributing any large number of copies, to +give them a chance to provide you with an updated version of the +Document. + +4. MODIFICATIONS + +You may copy and distribute a Modified Version of the Document under +the conditions of sections 2 and 3 above, provided that you release +the Modified Version under precisely this License, with the Modified +Version filling the role of the Document, thus licensing distribution +and modification of the Modified Version to whoever possesses a copy +of it. In addition, you must do these things in the Modified Version: + +A. Use in the Title Page (and on the covers, if any) a title distinct +from that of the Document, and from those of previous versions (which +should, if there were any, be listed in the History section of the +Document). You may use the same title as a previous version if the +original publisher of that version gives permission. B. List on the +Title Page, as authors, one or more persons or entities responsible +for authorship of the modifications in the Modified Version, together +with at least five of the principal authors of the Document (all of +its principal authors, if it has fewer than five), unless they release +you from this requirement. C. State on the Title page the name of the +publisher of the Modified Version, as the publisher. D. Preserve all +the copyright notices of the Document. E. Add an appropriate +copyright notice for your modifications adjacent to the other +copyright notices. F. Include, immediately after the copyright +notices, a license notice giving the public permission to use the +Modified Version under the terms of this License, in the form shown in +the Addendum below. G. Preserve in that license notice the full lists +of Invariant Sections and required Cover Texts given in the Document's +license notice. H. Include an unaltered copy of this License. I. +Preserve the section Entitled "History", Preserve its Title, and add +to it an item stating at least the title, year, new authors, and +publisher of the Modified Version as given on the Title Page. If there +is no section Entitled "History" in the Document, create one stating +the title, year, authors, and publisher of the Document as given on +its Title Page, then add an item describing the Modified Version as +stated in the previous sentence. J. Preserve the network location, if +any, given in the Document for public access to a Transparent copy of +the Document, and likewise the network locations given in the Document +for previous versions it was based on. These may be placed in the +"History" section. You may omit a network location for a work that was +published at least four years before the Document itself, or if the +original publisher of the version it refers to gives permission. K. +For any section Entitled "Acknowledgements" or "Dedications", Preserve +the Title of the section, and preserve in the section all the +substance and tone of each of the contributor acknowledgements and/or +dedications given therein. L. Preserve all the Invariant Sections of +the Document, unaltered in their text and in their titles. Section +numbers or the equivalent are not considered part of the section +titles. M. Delete any section Entitled "Endorsements". Such a section +may not be included in the Modified Version. N. Do not retitle any +existing section to be Entitled "Endorsements" or to conflict in title +with any Invariant Section. O. Preserve any Warranty Disclaimers. If +the Modified Version includes new front-matter sections or appendices +that qualify as Secondary Sections and contain no material copied from +the Document, you may at your option designate some or all of these +sections as invariant. To do this, add their titles to the list of +Invariant Sections in the Modified Version's license notice. These +titles must be distinct from any other section titles. + +You may add a section Entitled "Endorsements", provided it contains +nothing but endorsements of your Modified Version by various +parties--for example, statements of peer review or that the text has +been approved by an organization as the authoritative definition of a +standard. + +You may add a passage of up to five words as a Front-Cover Text, and a +passage of up to 25 words as a Back-Cover Text, to the end of the list +of Cover Texts in the Modified Version. Only one passage of +Front-Cover Text and one of Back-Cover Text may be added by (or +through arrangements made by) any one entity. If the Document already +includes a cover text for the same cover, previously added by you or +by arrangement made by the same entity you are acting on behalf of, +you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. + +The author(s) and publisher(s) of the Document do not by this License +give permission to use their names for publicity for or to assert or +imply endorsement of any Modified Version. + +5. COMBINING DOCUMENTS + +You may combine the Document with other documents released under this +License, under the terms defined in section 4 above for modified +versions, provided that you include in the combination all of the +Invariant Sections of all of the original documents, unmodified, and +list them all as Invariant Sections of your combined work in its +license notice, and that you preserve all their Warranty Disclaimers. + +The combined work need only contain one copy of this License, and +multiple identical Invariant Sections may be replaced with a single +copy. If there are multiple Invariant Sections with the same name but +different contents, make the title of each such section unique by +adding at the end of it, in parentheses, the name of the original +author or publisher of that section if known, or else a unique number. +Make the same adjustment to the section titles in the list of +Invariant Sections in the license notice of the combined work. + +In the combination, you must combine any sections Entitled "History" +in the various original documents, forming one section Entitled +"History"; likewise combine any sections Entitled "Acknowledgements", +and any sections Entitled "Dedications". You must delete all sections +Entitled "Endorsements." + +6. COLLECTIONS OF DOCUMENTS + +You may make a collection consisting of the Document and other +documents released under this License, and replace the individual +copies of this License in the various documents with a single copy +that is included in the collection, provided that you follow the rules +of this License for verbatim copying of each of the documents in all +other respects. + +You may extract a single document from such a collection, and +distribute it individually under this License, provided you insert a +copy of this License into the extracted document, and follow this +License in all other respects regarding verbatim copying of that +document. + +7. AGGREGATION WITH INDEPENDENT WORKS + +A compilation of the Document or its derivatives with other separate +and independent documents or works, in or on a volume of a storage or +distribution medium, is called an "aggregate" if the copyright +resulting from the compilation is not used to limit the legal rights +of the compilation's users beyond what the individual works permit. +When the Document is included in an aggregate, this License does not +apply to the other works in the aggregate which are not themselves +derivative works of the Document. + +If the Cover Text requirement of section 3 is applicable to these +copies of the Document, then if the Document is less than one half of +the entire aggregate, the Document's Cover Texts may be placed on +covers that bracket the Document within the aggregate, or the +electronic equivalent of covers if the Document is in electronic form. +Otherwise they must appear on printed covers that bracket the whole +aggregate. + +8. TRANSLATION + +Translation is considered a kind of modification, so you may +distribute translations of the Document under the terms of section 4. +Replacing Invariant Sections with translations requires special +permission from their copyright holders, but you may include +translations of some or all Invariant Sections in addition to the +original versions of these Invariant Sections. You may include a +translation of this License, and all the license notices in the +Document, and any Warranty Disclaimers, provided that you also include +the original English version of this License and the original versions +of those notices and disclaimers. In case of a disagreement between +the translation and the original version of this License or a notice +or disclaimer, the original version will prevail. + +If a section in the Document is Entitled "Acknowledgements", +"Dedications", or "History", the requirement (section 4) to Preserve +its Title (section 1) will typically require changing the actual +title. + +9. TERMINATION + +You may not copy, modify, sublicense, or distribute the Document +except as expressly provided for under this License. Any other attempt +to copy, modify, sublicense or distribute the Document is void, and +will automatically terminate your rights under this License. However, +parties who have received copies, or rights, from you under this +License will not have their licenses terminated so long as such +parties remain in full compliance. + +10. FUTURE REVISIONS OF THIS LICENSE + +The Free Software Foundation may publish new, revised versions of the +GNU Free Documentation License from time to time. Such new versions +will be similar in spirit to the present version, but may differ in +detail to address new problems or concerns. See +http://www.gnu.org/copyleft/. + +Each version of the License is given a distinguishing version +number. If the Document specifies that a particular numbered version +of this License "or any later version" applies to it, you have the +option of following the terms and conditions either of that specified +version or of any later version that has been published (not as a +draft) by the Free Software Foundation. If the Document does not +specify a version number of this License, you may choose any version +ever published (not as a draft) by the Free Software Foundation. + +\pagebreak +\paragraph*{\bf Preface} +To the casual observer, \TeX\ +is not a state-of-the-art typesetting system. +No flashy multilevel menus and interactive manipulation +of text and graphics dazzle the onlooker. +On a less superficial level, however, \TeX\ is a very sophisticated +program, first of all because of the ingeniousness of its +built-in algorithms for such things as paragraph breaking +and make-up of mathematical formulas, and +second because of its almost complete programmability. +The combination of these factors makes it possible for \TeX\ +to realize almost every imaginable layout in a highly automated +fashion. + +Unfortunately, it also means that \TeX\ has an +unusually large number of commands and parameters, +and that programming \TeX\ can be far from easy. +Anyone wanting to program in \TeX, and maybe +even the ordinary user, would seem to need two books: +a~tutorial that gives a first glimpse of the many +nuts and bolts of \TeX, and after that +a~systematic, complete reference manual. +This book tries to fulfil the latter function. +A~\TeX er who has already made a start +(using any of a number of introductory books +on the market) +should be able to use this book indefinitely thereafter. + +In this volume the universe of \TeX\ is presented as +about forty different subjects, each in a separate +chapter. +Each chapter starts out with a list of control sequences +relevant to the topic of that chapter +and proceeds to treat the +theory of the topic. +Most chapters conclude with remarks and examples. + +Globally, the chapters are ordered as follows. +The chapters on basic mechanisms are first, +the chapters on text treatment and mathematics are next, +and finally there are some +chapters on output and aspects of \TeX's connections to +the outside world. +% +The book also contains a glossary of \TeX\ +commands, tables, +and indexes by example, by control sequence, and by subject. +The subject index refers for most concepts to +only one page, where most of the information +on that topic can be found, as well as references +to the locations of related information. + +This book does not treat any specific \TeX\ macro package. +Any parts of the plain format that are treated are those +parts that belong to the `core' of plain \TeX: they +are also present in, for instance, \LaTeX. +Therefore, most remarks about the plain format +are true for \LaTeX, as well as most other formats. +Putting it differently, +if the text refers to the plain format, this should be taken +as a contrast to pure \IniTeX, not to \LaTeX. +By way of illustration, occasionally macros from plain \TeX\ +are explained that do not belong to the core. + +\medskip\noindent +{\bf Acknowledgment}\nl +I am indebted to Barbara Beeton, Karl Berry, and Nico Poppelier, +who read previous versions of this book. Their comments +helped to improve the presentation. +Also I~would like to thank the participants of +the discussion lists \TeX hax, \TeX-nl, and {\tt comp.text.tex}. +Their questions and answers gave me much food for thought. +Finally, any acknowledgement in a book about \TeX\ ought to +include Donald Knuth for inventing \TeX\ in the +first place. This book is no exception. + +\begin{flushright} + Victor Eijkhout\\ + Urbana, Illinois, August 1991\\ + Knoxville, Tennessee, May 2001 +\end{flushright} +\pagebreak + +\chapter{The Structure of the \TeX\ Processor} + +This book treats the various aspects of \TeX\ in chapters +that are concerned with relatively small, well-delineated, +topics. In this chapter, therefore, +a global picture of the way \TeX\ operates will be given. +Of necessity, many details will be omitted here, but all of +these are treated in later chapters. On the other hand, +the few examples given in this chapter will be repeated +in the appropriate places later on; they are included here +to make this chapter self-contained. + +%\point Four \TeX\ processors +\section{Four \TeX\protect\ processors} + +The way \TeX\ processes its input can be viewed as +happening on four levels. One might say that +the \TeX\ processor is split into four separate units, +each one accepting the output of the previous stage, and +delivering the input for the next stage. The input of +the first stage is then the \n{.tex} input file; the output +of the last stage is a \n{.dvi} file. + +For many purposes it is most convenient, and most insightful, +to consider these four levels of processing as happening +after one another, each one accepting the {\em completed\/} +output of the previous level. In reality this is not true: +all levels are simultaneously +active, and there is interaction between them. + +The four levels are (corresponding roughly +to the `eyes', `mouth', `stomach', and `bowels' respectively +in Knuth's original terminology) as follows. +\begin{enumerate}\item +The input processor. This is the piece of \TeX\ that +accepts input lines from the file system of whatever computer +\TeX\ runs on, and turns them into tokens. +Tokens are the internal objects of \TeX: +there are character tokens that constitute the typeset +text, and control sequence tokens that are commands +to be processed by the next two levels. +\item The expansion processor. +Some but not all of the tokens generated in the first level +\ldash macros, conditionals, and a number +of primitive \TeX\ commands \rdash are subject to expansion. +Expansion is the process that replaces some (sequences of) +tokens by other (or no) tokens. +\item The execution processor. +Control sequences that are not expandable are executable, +and this execution takes place on the third level of the +\TeX\ processor. + +One part of the activity here concerns changes to +\TeX's internal state: assignments (including +macro definitions) are typical activities in this +\awp +category. The other major thing happening on this level +is the construction of horizontal, vertical, and +mathematical lists. +\item The visual processor. +In the final level of processing +the visual part of \TeX\ processing is performed. Here +horizontal lists are broken into paragraphs, +vertical lists are broken into pages, +and formulas are built out of math lists. +Also the output to the \n{dvi} file takes place on this level. +The algorithms working here are not accessible to the user, +but they can be influenced by a number of parameters. +\end{enumerate} + +%\point The input processor +\section{The input processor} + +The input processor of \TeX\ is that part of \TeX\ that +translates whatever characters it gets from the input file +into tokens. The output of this processor is a stream +of tokens: a token list. Most tokens fall into one of two categories: +character tokens and control sequence tokens. +The remaining category is that of the parameter tokens; +these will not be treated in this chapter. + +%\spoint Character input +\subsection{Character input} + +For simple input text, characters are made into +character tokens. However, \TeX\ can ignore input characters: +a row of spaces in the input is usually equivalent to just one +space. Also, \TeX\ itself can insert tokens that do not correspond +to any character in the input, for instance the space token +at the end of the line, or the \cs{par} token after an empty line. + +Not all character tokens signify characters to be typeset. +\altt +Characters fall into sixteen categories \ldash each one +specifying a certain function that a character can have \rdash +of which only two contain the characters that will be +typeset. The other categories contain such characters +as~\n{\char`\{}, \n{\char`\}}, +\n\&, and~\n\#. A~character token can be considered +as a pair of numbers: the character code \ldash typically the \ascii\ +code \rdash and the category code. +It is possible to change +the category code that is associated with a particular +character code. + +When the escape character (by default~\cs{}$\,$) appears in the input, +\TeX's behaviour in forming tokens is more complicated. +Basically, +\TeX\ builds a control sequence by taking a number of characters +from the input and lumping them together into a single token. + +The behaviour with which \TeX's input processor +reacts to category codes can be described +as a machine that switches between three internal states: +$N$,~new line; $M$,~middle of line; $S$,~skipping spaces. +These states and the transitions between them are treated +in Chapter~\ref{mouth}. + +%\spoint Two-level input processing +\subsection{Two-level input processing} + +\TeX's input processor is in fact itself a two-level processor. +Because of limitations of the terminal, the editor, or the operating +\awp +system, the user may not be able to input certain desired characters. +Therefore, \TeX\ provides a mechanism to access +with two superscript characters all of the available character +positions. This may be considered +a separate stage of \TeX\ processing, taking place +prior to the three-state machine mentioned above. + +For instance, the sequence \verb>^^+> is replaced by~\n{k} because +the \ascii{} codes of \n k and \n + differ by~64. +Since this replacement takes place before tokens are formed, +writing \verb>\vs^^+ip 5cm> has the same effect as +\verb>\vskip 5cm>. Examples more useful than this exist. + +Note that this first stage is a transformation from +characters to characters, without considering category +codes. These come into play only in the second phase +of input processing where characters are converted +to character tokens by coupling the category code +to the character code. + +%\point The expansion processor +\section{The expansion processor} + +\TeX's expansion processor accepts a stream of tokens +and, if possible, +expands the tokens in this stream one by one +until only unexpandable tokens remain. +Macro expansion is the clearest example of this: +if a control sequence is a macro name, it is replaced +(together possibly with parameter tokens) by +the definition text of the macro. + +Input for the expansion processor is provided mainly +by the input processor. The stream of tokens coming +from the first stage of \TeX\ processing is subject +to the expansion process, and the result is a stream +of unexpandable tokens which is fed to the execution processor. + +However, the expansion processor comes into play +also when (among others) an \cs{edef} or \cs{write} is processed. +The parameter token list of these commands is +expanded very much as if the lists had been +on the top level, instead of the argument to a command. + +%\spoint The process of expansion +\subsection{The process of expansion} + +Expanding a token consists of the following steps: +\begin{enumerate} +\item See whether the token is expandable. +\item If the token is unexpandable, pass it to the token + list currently being built, and take on the next token. + +\item If the token is expandable, replace it by its expansion. + For macros without parameters, and a few primitive commands + such as \cs{jobname}, this is indeed a simple replacement. + Usually, however, \TeX\ needs to absorb some argument tokens from + the stream in order to be able to form the replacement + of the current token. + For instance, if the token was a macro with parameters, + sufficiently many tokens need to be absorbed to form + the arguments corresponding to these parameters. + +\item Go on expanding, starting with the first token of the + expansion. +\end{enumerate} +% +Deciding whether a token is expandable is +a simple decision. Macros and active characters, +conditionals, and a number of primitive \TeX\ commands +\awp +(see the list on page~\pageref{expand:lijst}) +are expandable, other tokens are not. +Thus the expansion processor replaces macros by their expansion, +it evaluates conditionals and eliminates any irrelevant parts of +these, but tokens such as \cs{vskip} and character tokens, +including characters such as dollars and braces, are passed untouched. +%\endinput +%\spoint Special cases: \cs{expandafter}, \cs{noexpand}, and \cs{the} +\subsection{Special cases: \cs{expandafter}, \cs{noexpand}, and \cs{the}} + +As stated above, +after a token has been expanded, \TeX\ will start expanding +the resulting tokens. At first sight the \cs{expandafter} +command would seem to be an exception to this rule, because +it expands only one step. What actually happens is that +the sequence \begin{disp}\cs{expandafter}\gr{token$_1$}\gr{token$_2$}\end{disp} +is replaced by +\begin{disp}\gr{token$_1$}\gr{\italic expansion of token$_2$}\end{disp} +and this replacement is in fact reexamined by the expansion +processor. + +Real exceptions do exist, however. If the +current token is the \cs{noexpand} command, the next +token is considered for the moment to be unexpandable: +it is handled as if it were \cs{relax}, and it is +passed to the token list being built. + +For example, +in the macro definition +\begin{verbatim} +\edef\a{\noexpand\b} +\end{verbatim} +the replacement text \verb>\noexpand\b> is expanded at definition +time. The expansion of \cs{noexpand} is the next token, with +a temporary meaning of \cs{relax}. Thus, when the expansion +processor tackles the next token, the~\cs{b}, it will consider +that to be unexpandable, and just pass it to the token list +being built, which is the replacement text of the macro. + +Another exception is that the tokens +resulting from \cs{the}\gr{token variable} +are not expanded further if this statement occurs +inside an \cs{edef} macro definition. + +%\spoint Braces in the expansion processor +\subsection{Braces in the expansion processor} + +Above, it was said that braces are passed as unexpandable +character tokens. In general this is true. For instance, +the \cs{romannumeral} command is handled by the expansion +processor; when confronted with +\begin{verbatim} +\romannumeral1\number\count2 3{4 ... +\end{verbatim} +\TeX\ will expand until the brace is encountered: +if \cs{count2} has the value of zero, the result will be +the roman numeral representation of~\n{103}. + +As another example, \begin{verbatim} +\iftrue {\else }\fi +\end{verbatim} +is handled by the expansion processor +completely analogous to +\begin{disp}\cs{iftrue} {\italic a}\cs{else} {\italic b}\cs{fi}\end{disp} +\awp +The result is a character token, independent of its category. + +However, in the context of macro expansion +the expansion processor will +recognize braces. +First of all, a balanced pair of braces marks off a group of tokens +to be passed as one argument. +If a macro has an argument \begin{verbatim} +\def\macro#1{ ... } +\end{verbatim} +one can call it with a single token, as in +\begin{verbatim} +\macro 1 \macro \$ +\end{verbatim} +or with a group of tokens, surrounded by braces +\begin{verbatim} +\macro {abc} \macro {d{ef}g} +\end{verbatim} + + +Secondly, when the arguments for a macro with +parameters are read, no expressions with unbalanced braces +are accepted. In +\begin{verbatim} +\def\a#1\stop{ ... } +\end{verbatim} +the argument consists of all +tokens up to the first occurrence of \cs{stop} +that is not in braces: in +\begin{verbatim} +\a bc{d\stop}e\stop +\end{verbatim} +the argument of~\cs{a} is \verb>bc{d\stop}e>. +Only balanced expressions +are accepted here. + +%\point The execution processor +\section{The execution processor} + +The execution processor builds lists: horizontal, vertical, +and math lists. Corresponding to these lists, it works +in horizontal, vertical, or math mode. Of these three modes +`internal' and `external' variants exist. +In addition to building lists, this part of the \TeX\ processor +also performs mode-independent processing, such as +assignments. + +Coming out of the expansion processor is a stream of +unexpandable tokens to be processed by +the execution processor. +\relax From the point of view of the execution processor, this +stream contains two types of tokens: +\begin{itemize} +\item Tokens signalling an assignment (this includes + macro definitions), and + other tokens signalling actions + that are independent of the mode, such + as \cs{show} and \cs{aftergroup}. +\item Tokens that build lists: + characters, boxes, and glue. The way they are handled + depends on the current mode. +\end{itemize} + +Some objects can be used in any mode; for instance boxes +can appear in horizontal, vertical, and math lists. +The effect of such an object will of course still depend on the mode. +Other objects are specific for one mode. +For instance, characters (to be more precise: +character tokens of categories 11 and~12), +are intimately connected to horizontal mode: +if the execution processor +is in vertical mode when it encounters a character, it will +switch to horizontal mode. + +Not all character tokens signal characters to be typeset: +the execution processor can also encounter math shift +\awp +characters (by default~\n{\char`\$}) and beginning/end of group +characters (by default \n{\char`\{} and~\n{\char`\}}). +Math shift characters let \TeX\ enter or exit +math mode, and braces let it enter or exit a~new level of +grouping. + +One control sequence handled by the execution processor +deserves special mention: \cs{relax}. +This control sequence is not expandable, but the execution +is to do nothing. Compare the effect of \cs{relax} in +\begin{verbatim} +\count0=1\relax 2 +\end{verbatim} +with that of \cs{empty} +defined by \begin{verbatim} +\def\empty{} +\end{verbatim} +in +\begin{verbatim} +\count0=1\empty 2 +\end{verbatim} +In the first case the expansion +process that is forming the number stops at \cs{relax} and +the number {\tt 1} is assigned; in the second case +\cs{empty} expands to nothing, so {\tt 12} is assigned. + +%\point The visual processor +\section{The visual processor} + +\TeX's output processor encompasses those algorithms that +are outside direct user control: paragraph breaking, +alignment, page breaking, math typesetting, and \n{dvi} file +generation. Various parameters control the operation +of these parts of \TeX. + +Some of these algorithms return their results in a form that +can be handled by the execution processor. For instance, +a paragraph that has been broken into lines is added to +the main vertical list as a sequence of horizontal boxes +with intermediate glue and penalties. Also, the page breaking +algorithm stores its result in \cs{box255}, so output +routines can dissect it. On the other hand, a math formula +can not be broken into pieces, and, naturally, +shipping a box to the \n{dvi} file is irreversible. + +%\point Examples +\section{Examples} + +%\spoint Skipped spaces +\subsection{Skipped spaces} + +Skipped spaces provide an illustration of the view that +\TeX's levels of processing accept the completed input +of the previous level. Consider the commands +\begin{verbatim} +\def\a{\penalty200} +\a 0 +\end{verbatim} +This is {\italic not\/} equivalent to +\begin{verbatim} +\penalty200 0 +\end{verbatim} +\awp +which would place a penalty of \n{200}, and +typeset the digit~\n0. Instead it expands to +\begin{verbatim} +\penalty2000 +\end{verbatim} +because the space after \cs{a} is skipped in the +input processor. Later stages of processing then receive +the sequence \begin{verbatim} +\a0 +\end{verbatim} + +%\spoint Internal quantities and their representations +\subsection{Internal quantities and their representations} + +\TeX\ uses various sorts of internal quantities, +such as integers and dimensions. These internal +quantities have an external representation, +which is a string of characters, such as +\n{4711} or~\n{91.44cm}. + +Conversions between the internal value and the external +representation take place on two different levels, +depending on what direction the conversion goes. +A~string of characters is converted to an internal +value in assignments such as +\begin{verbatim} +\pageno=12 \baselineskip=13pt +\end{verbatim} +or statements such as +\begin{verbatim} +\vskip 5.71pt +\end{verbatim} +and all of these statements are handled by the execution +processor. + +On the other hand, the conversion of the internal +values into a representation as a string of +characters is handled by the expansion processor. +For instance, \begin{verbatim} +\number\pageno \romannumeral\year +\the\baselineskip +\end{verbatim} +are all processed by expansion. + +As a final example, suppose \verb>\count2=45>, and +consider the statement +\begin{verbatim} +\count0=1\number\count2 3 +\end{verbatim} +The expansion processor tackles \verb>\number\count2> +to give the characters \n{45}, and the space after +the \n 2 does not end the number being assigned: +it only serves as a delimiter +of the number of the \cs{count} register. +In the next stage of processing, the execution processor +will then see the statement +\begin{verbatim} +\count0=1453 +\end{verbatim} +and execute this. + +%\endinput + +%%%% end of input file [bigpic] + +%\InputFile:mouth +%%%% this is input file [mouth] +%\tracingmacros=2 \tracingcommands\tracingmacros +%\subject[mouth] Category Codes \nl and Internal States +\endofchapter +\chapter{Category Codes and Internal States}\label{mouth} + +When characters are read, +\TeX\ assigns them +category codes. The reading mechanism has three internal +states, and transitions between these states are effected +by category codes of characters in the input. +This chapter describes how \TeX\ reads its input and +how the category codes of characters influence the +reading behaviour. Spaces and line ends are discussed. + +\begin{inventory} +\item [\cs{endlinechar}] + The character code of the end-of-line character + appended to input lines. + \IniTeX\ default:~13. +\item [\cs{par}] + Command to close off a paragraph and go into vertical mode. + Is generated by empty lines. + +\item [\cs{ignorespaces}] + Command that reads and expands until something is + encountered that is not a \gr{space token}. + +\item [\cs{catcode}] + Query or set category codes. + +\item [\cs{ifcat}] + Test whether two characters have the same category code. + +\item [\cs{\char32}] + Control space. + Insert the same amount of space that a space token would + when \cs{spacefactor}${}=1000$. + +\item [\cs{obeylines}] + Macro in plain \TeX\ to make line ends significant. + +\item [\cs{obeyspaces}] + Macro in plain \TeX\ to make (most) spaces significant. +\end{inventory} + +%\point Introduction +\section{Introduction} + +\TeX's input processor scans input lines from a file or terminal, and +makes tokens out of the characters. +The input processor can be viewed as +a simple finite state automaton with three internal states; +depending on the state its scanning behaviour may differ. +This automaton will be treated here both from the point of view of the +internal states and of the category codes governing the +transitions. + +%\point Initial processing +\section{Initial processing} + +Input from a file (or from the user terminal, but this +will not be mentioned specifically +most of the time) is handled one line at a time. +Here follows a discussion of what exactly is an input line +for \TeX. + +Computer systems differ with respect to +\term line! input\par\term line! end\par\term machine independence\par +the exact definition of an input +\mdqon +line. The carriage return/""line feed +\mdqoff +\awp +\message{slash-dash}% +sequence terminating a line is most common, +but some systems use just a line feed, and +some systems with fixed record length (block) storage do not have +a line terminator at all. Therefore \TeX\ has its +own way of terminating an input line. + +\begin{enumerate} +\item An input line is read from an input file (minus the +line terminator, if any). +\item Trailing spaces are removed (this is for the systems +with block storage, and it prevents confusion because these +spaces are hard to see in an editor). +\item The \cstoidx endlinechar\par, by default \gram{return} +(code~13) is appended. +If the value of \cs{endlinechar} is negative +\label{append:elc}% +or more than~255 (this was 127 in versions of \TeX\ older +than version~3; see page~\pageref{2vs3} for more differences), +no character is appended. +The effect then is the same as +if the line were to end with a comment character. +\end{enumerate} + + +Computers may also differ in the character encoding +(the most common schemes are \ascii{} and \ebcdic{}), so \TeX\ +converts the characters that are read from the file to its +own character codes. These codes are then used exclusively, +so that \TeX\ will perform the same on any system. +For more on this, see Chapter~\ref{char}. + +%\point Category codes +\section{Category codes} + +Each of the 256 character codes (0--255) has an +\term category codes\par +associated category code, though not necessarily always the same one. +There are 16 categories, numbered 0--15. +When scanning the input, \TeX\ +thus forms character-code--category-code pairs. +The input processor sees only these pairs; from them are formed +character tokens, control sequence tokens, and parameter tokens. +These tokens are then passed to \TeX's expansion and execution +processes. + +A~character token is a character-code--category-code +pair that is passed unchanged. +A~control sequence token consists of one or more characters +preceded by an escape character; see below. +Parameter tokens are also explained below. + +This is the list of the categories, together with a brief +description. More elaborate explanations follow in this and +later chapters. +\begin{enumerate} \message{set counter}%\SetCounter:item=-1 +\setcounter{enumi}{-1} +\item\label{ini:esc} Escape character; this signals the start of a control + sequence. \IniTeX\ makes the backslash \verb-\- (code~92) + an escape character. +\item Beginning of group; such a character causes \TeX\ to enter a new + level of grouping. The plain format makes the open brace \verb-{- +\mdqon + a beginning"-of-group character. +\mdqoff +\item End of group; \TeX\ closes the current level of grouping. + Plain \TeX\ has the closing brace \verb-}- as end-of-group + character. +\item Math shift; this is the opening and closing delimiter for + math formulas. Plain \TeX\ uses the dollar sign~\verb-$- + for this. +\item Alignment tab; the column (row) separator in tables + made with \cs{halign} (\cs{valign}). In plain + \TeX\ this is the ampersand~\verb-&-. +\item\label{ini:eol} End of line; a character that \TeX\ considers + to signal the + end of an input line. + \IniTeX\ assigns this code to the \gram{return}, that is, code~13. + Not coincidentally, 13~is also the value that \IniTeX\ + assigns to the \cs{endlinechar} parameter; see above. +\awp +\item Parameter character; this indicates parameters for macros. + In plain \TeX\ this is the hash sign~\verb-#-. +\item Superscript; this precedes superscript expressions + in math mode. It is also used to denote character + codes that cannot + be entered in an input file; see below. + In plain \TeX\ this is the circumflex~\verb-^-. +\item Subscript; this precedes subscript expressions in math mode. + In plain \TeX\ the underscore~\verb-_- is used for this. +\item Ignored; characters of this category are removed + from the input, and have therefore no influence on + further \TeX\ processing. In plain \TeX\ this is + the \gr{null} character, that is, code~0. +\item\label{ini:sp} Space; space characters receive special treatment. + \IniTeX\ assigns this category to the \ascii{} \gr{space} + character, code~32. +\item\label{ini:let} Letter; in \IniTeX\ only the characters \n{a..z}, \n{A..Z} + are in this category. Often, macro packages make + some `secret' character (for instance~\n@) into a letter. +\item\label{ini:other} Other; \IniTeX\ puts everything that is + not in the other categories into this category. Thus + it includes, for instance, digits and punctuation. +\item Active; active characters function as a \TeX\ command, + without being preceded by an escape character. + In plain \TeX\ this is only the tie character~\verb-~-, + which is defined to produce + an unbreakable space; see page~\pageref{tie}. +\item\label{ini:comm} Comment character; from a comment character onwards, + \TeX\ considers the rest of an input line to be + comment and ignores it. In \IniTeX\ the per cent sign \verb-%- + is made a comment character. +\item\label{ini:invalid} Invalid character; this category is for characters that + should not appear in the input. \IniTeX\ assigns the + \ascii\ \gr{delete} character, code~127, to this category. +\end{enumerate} + +The user can change the mapping +of character codes to category codes +with the \cstoidx catcode\par\ command (see Chapter~\ref{gramm} +for the explanation of concepts such as~\gr{equals}): +\begin{disp}\cs{catcode}\gram{number}\gr{equals}\gram{number}.\end{disp} +In such a statement, the first number is often given in the form +\begin{disp}\verb>`>\gr{character}\quad or\quad \verb>`\>\gr{character}\end{disp} +both of which denote the character code of the character +(see pages \pageref{char:code} and~\pageref{int:denotation}). + +The plain format defines +\csterm active\par +\begin{verbatim} +\chardef\active=13 +\end{verbatim} +so that one can write statements such as +\begin{verbatim} +\catcode`\{=\active +\end{verbatim} +The \cs{chardef} command is treated +on pages \pageref{chardef} and~\pageref{num:chardef}. + +The \LaTeX\ format has the control sequences +\begin{verbatim} +\def\makeatletter{\catcode`@=11 } +\def\makeatother{\catcode`@=12 } +\end{verbatim} +in order to switch on and off the `secret' character~\n@ +(see below). +\awp + +The \cs{catcode} command can also be used to query category +codes: in \begin{verbatim} +\count255=\catcode`\{ +\end{verbatim} +it yields a number, which can be assigned. + +Category codes can be tested by +\begin{disp}\cs{ifcat}\gr{token$_1$}\gr{token$_2$}\end{disp} +\TeX\ expands whatever is after \cs{ifcat} until two +unexpandable tokens are found; these are then compared +with respect to their category codes. Control sequence +tokens are considered to have category code~16, +which makes them all equal to each other, and unequal to +all character tokens. +Conditionals are treated further in Chapter~\ref{if}. + +%\point From characters to tokens +\section{From characters to tokens} + +The input processor +of \TeX\ scans input lines from a file or from the +user terminal, and converts the characters in the input +to tokens. There are three types of tokens. +\begin{itemize}\item Character tokens: any character that is + passed on its own to \TeX's +further levels of processing with an appropriate +category code attached. +\item Control sequence tokens, of which there are two kinds: + an escape character +\ldash that is,\message{ldash nobreak?} +a character of category~0 \rdash followed +by a string of `letters' is +lumped together into a {\em control word}, which is a single token. +An escape character followed by a single character that is not of +category~11, letter, is made into a +{\em control symbol}\term control! symbol\par. +If the distinction between control word and control symbol is +irrelevant, both are called +{\em control sequences}\term control! sequence\par. + +The control symbol that results from an escape character followed +\csterm \char32\par +by a space character is called +{\em control space}\term control! space\par. + +\item Parameter tokens: a parameter character + \ldash that is, a character of category~6, by default~\verb=#= \rdash +followed by a digit \n{1..9} is replaced by a parameter token. +Parameter tokens are allowed only in the context of +macros (see Chapter~\ref{macro}). + +A macro parameter character followed by another macro parameter +character (not necessarily with the same character code) +is replaced by a single character token. +This token has category~6 (macro parameter), and the character +code of the second parameter character. +The most common instance is of this is +replacing \n{\#\#} by~\n{\#$_6$}, where the subscript +denotes the category code. + +\end{itemize} + +%\point[input:states] The input processor as a finite state automaton +\section{The input processor as a finite state automaton} +\label{input:states} + +\TeX's input processor can be considered to be a finite state +automaton with three internal states, +that is, at any moment in time it is in one of three states, +\term state! internal\par +and after transition to another state there is no memory of the +\awp +previous states. + +%\spoint State {\italic N}: new line +\subsection{State {\italic N}: new line} + +State {\italic N} is entered at the beginning of each new input line, +and that is the only time \TeX\ is in this state. +In state~{\italic N} all space tokens (that is, characters of category~10) +are ignored; an end-of-line character is converted +into a \cs{par} token. +All other tokens bring \TeX\ into state~{\italic M}. + +%\spoint State {\italic S}: skipping spaces +\subsection{State {\italic S}: skipping spaces} + +State {\italic S} is entered in any mode after a control word or +control space (but after no other control symbol), +or, when in state~{\italic M}, after a space. +In this state all subsequent spaces or end-of-line characters +in this input line are discarded. + +%\spoint State {\italic M}: middle of line +\subsection{State {\italic M}: middle of line} + +By far the most common state is~{\italic M}, `middle of line'. +It is entered after characters of categories +1--4, 6--8, and 11--13, and after control symbols +other than control space. +An end-of-line character encountered in this state +results in a space token. + +\input figflow \message{left align flow diagram} +\vskip12pt plus 1pt minus 4pt\relax %before spoint skip +\begin{tdisp}%\PopIndentLevel +\leavevmode\relax +%\figmouth +\message{fig mouth missing} +\end{tdisp} + + +%\point[hathat] Accessing the full character set +\section{Accessing the full character set} +\label{hathat} + +Strictly speaking, \TeX's input processor +is not a finite state automaton. +This is because during the scanning of the input line +all trios consisting of two {\sl equal\/} superscript characters +\term \char94\char94\ replacement\par +(category code~7) and a subsequent character +(with character code~$<128$) +are replaced by a single character with a character +code in the range 0--127, +differing by 64 from that of the original character. + +This mechanism can be used, for instance, to access positions in a font +corresponding to character codes that cannot +be input, for instance because they are \ascii{} control characters. +The most obvious examples are the \ascii{} \gr{return} +and \gr{delete} characters; the corresponding +positions 13 and 127 in a font are +accessible as \verb>^^M> and~\verb>^^?>. +However, since the category of \verb>^^?> is 15, invalid, +that has to be changed before character 127 can be accessed. +\awp + +In \TeX3 this mechanism has been +modified and extended to access 256 characters: +any quadruplet \verb-^^xy- where both \n x and \n y are lowercase +hexadecimal digits \n0--\n9, \n a--\n f, +is replaced by a character in the +range 0--255, namely the character the number of which is +represented hexadecimally as~\n{xy}. +This imposes a slight restriction on the applicability +of the earlier mechanism: if, for instance, \verb>^^a> +is typed to produce character~33, then a following +\n0--\n9, \n{a}--\n{f} will be misunderstood. + +While this process makes \TeX's input processor +somewhat more powerful +than a true finite state automaton, +it does not interfere with the rest of +the scanning. Therefore it is conceptually simpler to pretend that +such a replacement of triplets or quadruplets +of characters, starting with~\verb>^^>, is performed in advance. +In actual practice this is not possible, +because an +input line may assign category code~7 to some +character other than the circumflex, thereby +influencing its further processing. + + +%\point Transitions between internal states +\section{Transitions between internal states} + +Let us now discuss the effects on the internal state +of \TeX's input processor when +certain category codes are encountered in the input. + +%\spoint 0: escape character +\subsection{0: escape character} + +When an escape character is encountered\term character !escape\par, +\TeX\ starts forming a control sequence token. +Three different types of control sequence can result, +depending on the category code of the character that +follows the escape character. + +\begin{itemize}\item +If the character following the escape is of category~11, +letter, then \TeX\ combines the escape, +that character and all following +characters of category~11, into a control word. +After that \TeX\ +goes into state~{\italic S}, skipping spaces. +\item +With a character of category~10, space, +a control symbol called control space results, +and \TeX\ goes into state~{\italic S}. +\item +With a character of any other category code +a control symbol results, and \TeX\ goes into state~{\italic M}, +middle of line. +\end{itemize} + +The letters of a control sequence name have to be all on one line; +a control sequence name is not continued on the next line +if the current line ends with a comment sign, or if (by letting +\cs{endlinechar} be outside the range~0--255) +there is no terminating character. + +%\spoint 1--4, 7--8, 11--13: non-blank characters +\subsection{1--4, 7--8, 11--13: non-blank characters} + +Characters of category codes 1--4, 7--8, and 11--13 are made +into tokens, and \TeX\ goes into state~{\italic M}. + +%\spoint 5: end of line +\subsection{5: end of line} + +Upon encountering an end-of-line character, +\TeX\ discards the rest of the +line, and starts processing the next line, +in state~{\italic N}. If the current state was~{\italic N}, +\awp +that is, if the +line so far contained at most spaces, a~\cs{par} token +is inserted; if the state was~{\italic M}, a~space token is inserted, +and in state~{\italic S} nothing is inserted. + +Note that by `end-of-line character' a character with category +code~5 is meant. This is not necessarily the \cs{endlinechar}, +nor need it appear at the end of the line. +See below for further remarks on line ends. + +%\spoint 6: parameter +\subsection{6: parameter} + +Parameter characters \ldash usually~\verb=#= \rdash can be +\term character !parameter\par +followed by either a digit \n{1..9} +in the context of macro definitions +\altt +or by another parameter character. +In the first case a `parameter token' results, +in the second case only a single parameter character +is passed on as a character token for further processing. +In either case \TeX\ goes into state~{\italic M}. + +A parameter character can also appear on its own in an +alignment preamble (see Chapter~\ref{align}). + +%\spoint 7: superscript +\subsection{7: superscript} + +A superscript character is handled like most non-blank +characters, except in the case where it is followed +by a superscript character of the same character code. +The process +that replaces these two characters plus the following character +(possibly two characters in \TeX3) by another character +was described above. + +%\spoint 9: ignored character +\subsection{9: ignored character} + +Characters of category 9 are ignored; \TeX\ remains in the same state. + +%\spoint 10: space +\subsection{10: space} + +A token with category code 10 \ldash this is called a \gr{space token}, +irrespective of the character code \rdash +is ignored in states {\italic N} and~{\italic S} +(and the state does not change); +in state~{\italic M} \TeX\ goes into state~{\italic S}, inserting +a token that has category~10 and character code~32 +(\ascii{} space)\term character !space\par, +that is, the character code of the space token may change +from the character that was actually input. + +%\spoint 14: comment +\subsection{14: comment} + +A comment character causes \TeX\ to discard +the rest of the line, including the comment character. +In particular, the end-of-line character is not seen, +so even if the comment was encountered in state~{\italic M}, no space +token is inserted. + +%\spoint 15: invalid +\subsection{15: invalid} + +Invalid characters cause an error message. \TeX\ remains in +the state it was in. +However, in the context of a control symbol an invalid character +is acceptable. Thus \verb>\^^?> does not cause any error messages. +\awp + +%\point[cat12] Letters and other characters +\section{Letters and other characters} +\label{cat12} + +In most programming languages identifiers can consist +of both letters and digits (and possibly some other +character such as the underscore), but control sequences in \TeX\ +are only allowed to be formed out of characters of category~11, +letter. Ordinarily, the digits and punctuation symbols have +category~12, other character. +However, there are contexts where \TeX\ itself +generates a string of characters, all of which have +category code~12, even if that is not their usual +category code. + +This happens when the operations +\cs{string}, +\cs{number}, +\cs{romannumeral}, +\cs{jobname}, +\cs{fontname}, +\cs{meaning}, +and \cs{the} +are used to generate a stream of character tokens. +If any of the characters delivered by such a command +is a space character (that is, character code~32), +it receives category code~10, space. + +For the extremely rare case where a hexadecimal digit has been +hidden in a control sequence, \TeX\ allows \n A$_{12}$--\n F$_{12}$ +to be hexadecimal digits, in addition to the ordinary +\n A$_{11}$--\n F$_{11}$ (here +the subscripts denote the category codes). + +For example, +\begin{disp}\verb>\string\end>\quad gives four character tokens\quad +\n{\char92$_{12}$e$_{12}$n$_{12}$d$_{12}$} \end{disp} +Note that +\n{\char92$_{12}$}\term character !escape\par\label{use:escape} +is used in the output only because the +value of \cs{escapechar} is the character code for the +backslash. Another value of \cs{escapechar} leads to another +character in the output of \cs{string}. +The \cs{string} command is treated further in Chapter~\ref{char}. + +Spaces can wind up in control sequences: +\begin{disp}\verb>\csname a b\endcsname>\end{disp} gives a control sequence +token in which one of the three characters is a space. +Turning this control sequence token into a string of characters +\begin{disp}\verb>\expandafter\string\csname a b\endcsname>\end{disp} +gives \n{\char92$_{12}$a$_{12}$\char32$_{10}$b$_{12}$}. + + +As a more practical example, suppose there exists a sequence +of input files \n{file1.tex}, \n{file2.tex}\label{ex:jobnumber}, +and we want to +write a macro that finds the number of the input file +that is being processed. One approach would be to write +\begin{verbatim} +\newcount\filenumber \def\getfilenumber file#1.{\filenumber=#1 } +\expandafter\getfilenumber\jobname. +\end{verbatim} +where the letters \n{file} in the parameter text of the +macro (see Section~\ref{param:text}) absorb that part of the +jobname, leaving the number as the sole parameter. + +However, this is slightly incorrect: the letters \n{file} resulting +from the \cs{jobname} command have category code~12, instead of +11 for the ones in the definition of \cs{getfilenumber}. +This can be repaired as follows: +\begin{verbatim} +{\escapechar=-1 + \expandafter\gdef\expandafter\getfilenumber + \string\file#1.{\filenumber=#1 } +} +\end{verbatim} +\awp +Now the sequence \verb>\string\file> gives the four +letters \n{f$_{12}$i$_{12}$l$_{12}$e$_{12}$}; +the \cs{expandafter} commands let this be executed prior to +the macro definition; +the backslash is omitted because we put \verb>\escapechar=-1>. +Confining this value to a group makes it necessary to use~\cs{gdef}. + + +%\global\def\pppar.{\par} +%\point The \lowercase{\n{\char92par}} token +\section{The \lowercase{\n{\char92par}} token} + +\TeX\ inserts a \cstoidx par\par\ token into the input after +\term line !empty\par +encountering a character with category code~5, +end of line, in state~{\italic N}. +It is good to realize when exactly this happens: +since \TeX\ leaves state~{\italic N} +when it encounters any token but a space, +a~line giving a \cs{par} can only contain characters +of category~10. In particular, it cannot end with a comment +character. Quite often this fact is used the other way around: +if an empty line is wanted for the layout of the input +one can put a comment sign on that line. + + +Two consecutive empty lines generate two \cs{par} tokens. +For all practical purposes this is equivalent to one \cs{par}, +because after the first one \TeX\ enters vertical mode, and +in vertical mode a \cs{par} only +exercises the page builder, +and clears the paragraph shape parameters. + +A \cs{par} is also inserted into the input when \TeX\ sees a +\gram{vertical command} in unrestricted horizontal mode. +After the \cs{par} has been read and expanded, the +vertical command is examined anew (see Chapters~\ref{hvmode} +and~\ref{par:end}). + +The \cs{par} token may also be inserted by the \cs{end} +command that finishes off the run of \TeX; see Chapter~\ref{output}. + +It is important to realize that \TeX\ does what it normally does +when encountering an empty line +(which is ending a paragraph) +only because of the default definition of the \cs{par} token. +By redefining \cs{par} the behaviour +caused by empty lines and vertical commands can be changed completely, +and interesting special effects can be achieved. +In order to continue to be able to cause the actions normally +associated with \cs{par}, the synonym \cs{endgraf} is +available in the plain format. See further Chapter~\ref{par:end}. + +The \cs{par} token is not allowed to be part of a macro +argument, unless the macro has been declared to be \cs{long}. +A \cs{par} in the argument of a non-\cs{long} macro +prompts \TeX\ to give a `runaway argument' message. +Control sequences that have been \cs{let} to \cs{par} +(such as \cs{endgraf}) are allowed, however. + +%\point Spaces +\section{Spaces} + +This section treats some of the aspects of +\term token !space\par +space characters and space tokens in the initial processing +stages of \TeX. The topic of spacing in text typesetting +is treated in Chapter~\ref{space}. + + +%\spoint Skipped spaces +\subsection{Skipped spaces} + +From the discussion of the internal states of \TeX's +input processor +it is clear that some spaces in the input never reach the +\awp +output; in fact they never get past the input processor. +These are for instance the spaces at the beginning +of an input line, and the spaces following the one +that lets \TeX\ switch to state~{\italic S}. + + +On the other hand, line ends can generate spaces (which are not +in the input) that may wind up in the output. +There is a third kind of space: the spaces that get past the +input processor, +or are even generated there, but still do not wind up in the +output. These are the \gram{optional spaces} that the +syntax of \TeX\ allows in various places. + +%\spoint Optional spaces +\subsection{Optional spaces} + +The syntax of \TeX\ has the concepts of `optional spaces' +\term space! optional \par +and `one optional space': +\begin{disp}\gr{one optional space} $\longrightarrow$ +\gr{space token} $|$ \gr{empty}\nl +\gr{optional spaces} $\longrightarrow$ +\gr{empty} $|$ \gr{space token}\gr{optional spaces}\end{disp} +In general, \gr{one optional space} is allowed after +numbers and glue specifications, while \gr{optional spaces} are +allowed whenever a space can occur inside a number +(for example, between a minus sign and the digits of the number) +or glue specification (for example, between \n{plus} and \n{1fil}). +Also, the definition of \gr{equals} allows \gr{optional spaces} +before the \n= sign. + +Here are some examples of optional spaces. + +\begin{itemize} +\item A number can be delimited by \gr{one optional space}. +This prevents accidents (see Chapter~\ref{number}), +and it speeds up processing, as \TeX\ can +detect more easily where the \gram{number} being read ends. +Note, however, that not every `number' is a \gram{number}: +for instance the {\tt 2} in \cs{magstep2} is not a number, +but the single token that is the parameter of the +\cs{magstep} macro. Thus a space or line end after this +is significant. Another example is a parameter number, +for example~\n{\#1}: since at most nine parameters are allowed, scanning +one digit after the parameter character suffices. + +\item From the grammar of \TeX\ +it follows that the +keywords \n{fill} and \n{filll} +consist of \n{fil} and +separate {\tt l}$\,$s, each of which is a keyword +(see page~\pageref{keywords} for a more elaborate discussion), +and hence can be followed by optional spaces. +Therefore forms such as \hbox{\n{fil L l}} are also valid. +This is a potential source of strange accidents. +In most cases, appending a \cs{relax} token prevents +such mishaps. + +\item The primitive command \cstoidx ignorespaces\par\ +may come in handy as the final command in a macro definition. +As it gobbles up +optional spaces, it can be used to prevent spaces following the +closing brace of an argument from winding up in the output +inadvertently. For example, in +\begin{verbatim} +\def\item#1{\par\leavevmode + \llap{#1\enspace}\ignorespaces} +\item{a/}one line \item{b/} another line \item{c/} +yet another +\end{verbatim} +the \cs{ignorespaces} prevents spurious +spaces in the second and third item. +An empty line +after \cs{ignorespaces} will still insert a \cs{par}, however. +\end{itemize} +\awp + +%\spoint Ignored and obeyed spaces +\subsection{Ignored and obeyed spaces} + +After control words spaces are ignored. This is not an +instance of optional spaces, but it is due to the fact that +\TeX\ goes into state~{\italic S}, skipping spaces, after control +words. Similarly an end-of-line character is skipped +after a control word. + +Numbers are delimited by only \gr{one optional space}, +but still +\begin{disp}\n{a\char92 count0=3\char32\char32b}\quad gives\quad `ab',\end{disp} +because \TeX\ goes into state~{\italic S} after the first +space token. The second space is therefore skipped +in the input processor of \TeX; it never becomes a space token. + +Spaces are skipped furthermore when \TeX\ is in state~{\italic N}, +newline. When \TeX\ is processing in vertical mode +space tokens (that is, spaces that were not skipped) +are ignored. For example, the space inserted (because of the line end) +after the first box in +\begin{verbatim} +\par +\hbox{a} +\hbox{b} +\end{verbatim} +has no effect. + +Both plain \TeX\ and \LaTeX\ define a command \cs{obeyspaces} +\altt +that makes spaces significant: after one space other spaces are no +longer ignored. In both cases the basis is +\altt +\begin{verbatim} +\catcode`\ =13 \def {\space} +\end{verbatim} +However, there is a difference between the two cases: +in plain \TeX\ \begin{verbatim} +\def\space{ } +\end{verbatim} +while in \LaTeX\ \begin{verbatim} +\def\space{\leavevmode{} } +\end{verbatim} +although the macros bear other names there. + +The difference between the two macros becomes +apparent in the context of \cs{obeylines}: +each line end is then a \cs{par} command, implying that +each next line is started in vertical mode. +An active space is expanded by the plain macro to a space token, +which is ignored in vertical mode. +The active spaces in \LaTeX\ will immediately switch to horizontal +mode, so that each space is significant. + +%\spoint More ignored spaces +\subsection{More ignored spaces} + +There are three further places where \TeX\ will ignore space tokens. +\alt +\begin{enumerate} +\item When \TeX\ is looking for +an undelimited macro argument it will accept the +first token (or group) that is not a space. This is treated +in Chapter~\ref{macro}. + +\item In math mode space tokens are ignored (see Chapter~\ref{math}). + +\item After an alignment tab character spaces are ignored +(see Chapter~\ref{align}). +\end{enumerate} +\awp + +%\spoint \gr{space token} +\subsection{\gr{space token}} + +Spaces are anomalous in \TeX. +For instance, the \cs{string} operation +assigns category code~12 to all +characters except spaces; they receive category~10. +Also, as was said above, \TeX's input processor converts (when in +state~{\italic M}) all tokens with category code~10 into real spaces: +they get character code~32. +Any character token with category~10 is called +\gram{space token}\term space! token\par. +Space tokens with character +code not equal to 32 are called `funny spaces' +\term space !funny\par. + +\begin{example} After giving the character \n Q +the category code of a space character, +and using it in a definition +\begin{verbatim} +\catcode`Q=10 \def\q{aQb} +\end{verbatim} +we get +\begin{verbatim} +\show\q +macro:-> a b +\end{verbatim} +because the input processor +changes the character code of the funny space +in the definition. +\end{example} + +Space tokens with character codes other than 32 can be +created using, for instance, \cs{uppercase}. +However, `since the various forms of +space tokens are almost identical in behaviour, there's no +point dwelling on the details'; see~\cite{Knuth:TeXbook}~p.~377. + + +%\spoint Control space +\subsection{Control space} + +The `control space' command \verb-\-\n{\char32} +\cstoidx\char32\par\ +contributes the amount of space that a \gr{space token} would +when the \verb=\spacefactor= is~1000. +A~control space +is not treated like a space token, or like a macro +expanding to one (which is how \cs{space} is defined in plain \TeX). +For instance, \TeX\ ignores spaces +at the beginning of an input line, but +control space is a \gr{horizontal command}, so it +makes \TeX\ switch from vertical to horizontal mode +(and insert an indentation box). +See Chapter~\ref{space} for the space factor, and +chapter~\ref{hvmode} for horizontal and vertical modes. + +%\spoint `\n{\char32}' +\subsection{`\n{\char32}'} + +The explicit symbol `\n{\char32}' for a space +is character~32 in the Computer Modern typewriter typeface. +However, switching to \cs{tt} is not sufficient to get +spaces denoted this way, because spaces will still +receive special treatment in the input processor. + +One way to +let spaces be typeset by \n{\char32} +is to set \begin{verbatim} +\catcode`\ =12 +\end{verbatim} +\TeX\ will then take a space as the instruction to +typeset character number~32. Moreover, subsequent spaces +are not skipped, but also typeset this way: state~{\italic S} +\awp +is only entered after a character with category code~10. +Similarly, spaces after a control sequence are made +visible by changing the category code of the space character. + +%\point More about line ends +\section{More about line ends} + +\TeX\ accepts lines from an input file, excluding any line +terminator that may be used\term line! end\par. +Because of this, \TeX's behaviour here is not dependent +on the operating system and the line terminator it uses (\key{CR}-\key{LF}, +\key{LF}, or none at all for block storage). +From the input line any trailing spaces are removed. +The reason for this is historic; it has to do with +the block storage mode on \key{IBM} mainframe computers. +For some computer-specific problems with end-of-line +characters, see~\cite{B:ctrl-M}. + +A~terminator character is then appended +with a character code of \cs{endlinechar}, +unless this parameter has a value that +is negative or more than~255. +Note that this terminator character +need not have category code~5, end of line. + +%\spoint Obeylines +\subsection{Obeylines} + +Every once in a while it is desirable that the line ends in +\message{Check spurious space obeylines+1}% +\cstoidx obeylines\par\howto Change the meaning of the line end\par +the input correspond to those in the output. +The following piece of code does the trick: +\begin{verbatim} +\catcode`\^^M=13 % +\def^^M{\par}% +\end{verbatim} +The \cs{endlinechar} character is here made active, +and its meaning becomes \cs{par}. +The comment signs prevent \TeX\ from seeing the terminator of the +\alt +lines of this definition, and expanding it since it is active. + +However, it takes some care to embed this code in a macro. +The definition +\begin{verbatim} +\def\obeylines{\catcode`\^^M=13 \def^^M{\par}} +\end{verbatim} +will be misunderstood: +\TeX\ will discard everything +after the second \verb>^^M>, because this has category code~5. +Effectively, this line is then +\begin{verbatim} +\def\obeylines{\catcode`\^^M=13 \def +\end{verbatim} +To remedy this, +the definition itself has to be +performed in a context where \verb>^^M> is an active +character:\begin{verbatim} +{\catcode`\^^M=13 % + \gdef\obeylines{\catcode`\^^M=13 \def^^M{\par}}% +} +\end{verbatim} +Empty lines in the input are not taken into account +in this definition: these disappear, because two consecutive \cs{par} +tokens are (in this case) equivalent to one. +A slightly modified definition for the line end as +\begin{verbatim} +\def^^M{\par\leavevmode} +\end{verbatim} +remedies this: +now every line end forces \TeX\ to start a paragraph. For empty +lines this will then be an empty paragraph. +\awp + +%\spoint Changing the \cs{\endlinechar} +\subsection{Changing the \cs{endlinechar}} + +Occasionally you may want to change the \cs{endlinechar}, or +the \cs{catcode} of the ordinary line terminator \verb.^^M., +for instance to obtain special effects such as macros where +the argument is terminated by the line end. +See page~\pageref{pick:eol} for a worked-out example. + +There are a couple of traps. Consider the following: +\begin{verbatim} +{\catcode`\^^M=12 \endlinechar=`\^^J \catcode`\^^J=5 +... +... } +\end{verbatim} +This causes unintended output of both character~13 (\verb-^^M-) +and~10 (\verb-^^J-), caused by the line terminators of the +first and last line. + +Terminating the first and last line with a comment works, +but replacing the first line by the two lines +\begin{verbatim} +{\endlinechar=`\^^J \catcode`\^^J=5 +\catcode`\^^M=12 +\end{verbatim} +is also a solution. + +Of course, in many cases it is not necessary to substitute +another end-of-line character; a~much simpler solution +is then to put \begin{verbatim} +\endlinechar=-1 +\end{verbatim} +which treats all lines as if they end with a comment. + +%\spoint More remarks about the end-of-line character +\subsection{More remarks about the end-of-line character} + +The character that \TeX\ appends at the end of an input line +is treated like any other character. Usually one is not aware +of this, as its category code is special, but there are a few +ways to let it be processed in an unusual way. + +\begin{example} Terminating an input line with \verb>^^> will +(ordinarily, when \cs{endlinechar} is~13) give `M' in the output, +which is the +\ascii{} character with code~13+64. +\end{example} + +\begin{example} If \verb>\^^M> has been defined, +terminating an input line with a backslash will execute this command. +The plain format defines +\begin{verbatim} +\def\^^M{\ } +\end{verbatim} +which makes a `control return' equivalent to a control space. +\end{example} + +%\point More about the input processor +\section{More about the input processor} + +%\spoint The input processor as a separate process +\subsection{The input processor as a separate process} + +\TeX's levels of processing are all working at the +\awp +same time and incrementally, but conceptually they can often be +considered to be separate processes that each accept the +completed output of the previous stage. The juggling with +spaces provides a nice illustration for this. + +Consider the definition +\begin{verbatim} +\def\DoAssign{\count42=800} +\end{verbatim} +and the call +\begin{verbatim} +\DoAssign 0 +\end{verbatim} +The input processor, the part +of \TeX\ that builds tokens, in scanning this call +skips the space before the zero, so the expansion of this +call is \begin{verbatim} +\count42=8000 +\end{verbatim} +It would be incorrect to reason +`\cs{DoAssign} is read, then expanded, the space delimits the +number 800, so 800 is assigned and the zero is printed'. +Note that the same would happen if the zero appeared on the next line. + +Another illustration shows that optional spaces appear in a different +stage of processing from that for skipped spaces: +\begin{disp}\verb>\def\c.{\relax}>\nl + \verb>a\c.>{\tt\char32 b}\end{disp} +expands to +\begin{disp}\n{a\cs{relax}\char32 b}\end{disp} +which gives as output\begin{disp} `a b'\end{disp} +because spaces after the \cs{relax} control sequence are only +skipped when the line is first read, not when it is expanded. +The fragment +\begin{disp} \verb-\def\c.{\ignorespaces}-\nl \verb-a\c. b-\end{disp} +on the other hand, expands to +\begin{disp}\n{a\cs{ignorespaces}\char32 b}\end{disp} +Executing the \cs{ignorespaces} command removes the subsequent +space token, so the output is \begin{disp} `ab'.\end{disp} +In both definitions +the period after \cs{c} is a delimiting token; it is used here +to prevent spaces from being skipped. + +%\spoint The input processor not as a separate process +\subsection{The input processor not as a separate process} + +Considering the tokenizing of \TeX\ to be a separate process +is a convenient view, but sometimes it leads to confusion. +The line \begin{verbatim} +\catcode`\^^M=13{} +\end{verbatim} +\awp +makes the line end active, +and subsequently gives an `undefined control sequence' error +for the line end of this line itself. Execution of the commands +on the line thus influences the scanning process of that +same line. + +By contrast, \begin{verbatim} +\catcode`\^^M=13 +\end{verbatim} +does not give an error. +The reason for this is that \TeX\ reads the line end while it is still +scanning the number~13; that is, at a time when the assignment +has not been performed yet. +The line end is then converted to the optional space character +delimiting the number to be assigned. + +%\spoint Recursive invocation of the input processor +\subsection{Recursive invocation of the input processor} + +Above, the activity of replacing a parameter +character plus a digit by a parameter token was described +as something similar to the lumping together of letters +into a control sequence token. Reality is somewhat more +complicated than this. \TeX's token scanning mechanism +is invoked both for input from file and for input from +lists of tokens such as the macro definition. Only in the +first case is the terminology of internal states applicable. + +Macro parameter characters are treated the same in both +cases, however. If this were not the case it would +not be possible to write things such as +\begin{verbatim} +\def\a{\def\b{\def\c####1{####1}}} +\end{verbatim} +See page \pageref{nest:def} for an explanation of such +nested definitions. + +%\point The \verb@- convention +\section{The \n{@} convention} + +Anyone who has ever browsed through either the plain format or +the \LaTeX\ format will have noticed that a lot of control sequences +contain an `at' sign:~\verb-@-. These are control sequences that +are meant to be inaccessible to the ordinary user. + +Near the beginning of the format files the instruction +\begin{verbatim} +\catcode`@=11 +\end{verbatim} +occurs, making the at sign into a letter, +meaning that it can be used in control sequences. Somewhere near the +end of the format definition the at sign is made `other' again: +\begin{verbatim} +\catcode`@=12 +\end{verbatim} + +Now why is it that users cannot +call a control sequence with an at sign +directly, although they can call macros that contain lots of those +`at-definitions'? The reason is that the control sequences +containing an \n@ are internalized by \TeX\ at definition time, +after which they are a token, not a string of characters. +Macro expansion then +just inserts such tokens, and at that time the category codes +of the constituent characters do not matter any more. + +%%%% end of input file [mouth] + +%\InputFile:char +%%%% this is input file [char] +%\subject[char] Characters +\endofchapter +\chapter{Characters}\label{char} + +Internally, \TeX\ represents characters by their (integer) +character code. This chapter treats those codes, and the +commands that have access to them. + +\begin{inventory} +\item [\cs{char}] + Explicit denotation of a character to be typeset. + +\item [\cs{chardef}] + Define a control sequence to be a synonym for + a~character code. + +\item [\cs{accent}] + Command to place accent characters. + +\item [\cs{if}] + Test equality of character codes. + +\item [\cs{ifx}] + Test equality of both character and category codes. + +\item [\cs{let}] + Define a control sequence to be a synonym of a token. + +\item [\cs{uccode}] + Query or set + the character code that is the uppercase variant of a given code. + +\item [\cs{lccode}] + Query or set + the character code that is the lowercase variant of a given code. + +\item [\cs{uppercase}] + Convert the \gr{general text} argument to its uppercase form. + +\item [\cs{lowercase}] + Convert the \gr{general text} argument to its lowercase form. + +\item [\cs{string}] + Convert a token to a string of one or more characters. +\item [\cs{escapechar}] + Number of the character that is to be used + for the escape character + when control sequences are being converted + into character tokens. \IniTeX\ default:~92~(\cs{}). +\end{inventory} + +%\point[char:code] Character codes +\section{Character codes} +\label{char:code} + +Conceptually it is easiest to think that \TeX\ works with +\term character! codes\par +characters internally, but in fact +\TeX\ works with integers: the `character codes'. + +The way characters are encoded in a computer may differ +from system to system. +Therefore \TeX\ uses its own scheme of character codes. +Any character that is read from a file (or from the user terminal) +is converted to a character code according to the +character code table. +A~category code is then assigned based on this (see Chapter~\ref{mouth}). +The character code table is based on the 7-bit \ascii{} table +for numbers under~128 (see Chapter~\ref{table}). + +There is an explicit conversion between characters +(better: character tokens) +and character codes using the left quote (grave, back quote) +character~\n{`{}}: +at all places where \TeX\ expects a \gram{number} you +can use the left quote followed by a character +token or +a single-character control sequence. +Thus both \verb.\count`a. and \verb.\count`\a. are synonyms +\awp +for \verb.\count97.. See also Chapter~\ref{number}. + +The possibility of a single-character control +sequence is necessary in certain cases such as +\begin{disp}\verb>\catcode`\%=11>\quad or\quad \verb>\def\CommentSign{\char`\%}>\end{disp} +which would be misunderstood if the backslash were left out. +For instance \begin{verbatim} +\catcode`%=11 +\end{verbatim} +would consider +the \n{=11} to be a comment. +Single-character +control sequences can be formed from characters with any +category code. + +After the conversion to character codes any connection +with external representations has disappeared. Of course, +for most characters the visible output will `equal' the input +(that is, an `\n{a}' causes an~`a'). +There are exceptions, however, even among the common symbols. +In the Computer Modern +roman fonts there are no `less than' and `greater than' +\message{Check <>! Dammit!}% +signs, so the input `\verb.<>.' will give `<>' in the output. +%{\MathRMx<>} + +In order to make \TeX\ machine independent at the output +side, the character codes are also used in the \n{dvi} file: +opcodes $n=0\ldots127$ denote simply the instruction `take +character $n$ from the current font'. The complete definition +of the opcodes in a \n{dvi} file can be found in~\cite{Knuth:TeXprogram}. + + +%\point Control sequences for characters +\section{Control sequences for characters} + +There are a number of ways in which a control sequence can denote +a character. The \cs{char} command specifies a character to be +typeset; the \cs{let} command introduces +a synonym for a character token, that is, +the combination of character code and category code. + +%\point Denoting characters to be typeset: \cs\char +\section{Denoting characters to be typeset: \protect\cs{char}} + +Characters can be denoted numerically by, for example, +\verb.\char98.\cstoidx char\par. +This command tells \TeX\ to add character number~98 of the +current font to the horizontal list currently under construction. + +Instead of decimal notation, it is often more convenient to +use octal or hexadecimal notation. For octal the single quote is used: +\verb.\char'142.; hexadecimal uses the double quote: \verb.\char"62.. +Note that \verb.\char''62. is incorrect; the process that replaces +two quotes by a double quote works at a later stage of processing +(the visual processor) than number scanning (the execution processor). + +Because of the explicit conversion to character codes by the +back quote character it is also possible to get a `b' \ldash provided +that you are using a font organized a bit like the \ascii{} table \rdash +with \verb.\char`b. or \verb.\char`\b.. + +The \cs{char} command looks superficially a bit like +the \verb-^^- substitution mechanism (Chapter~\ref{mouth}). +Both mechanisms access characters without directly denoting them. +However, the \verb-^^- mechanism operates in a very early stage of +processing (in the input processor of \TeX, +but before category code +assignment); the \cs{char} command, on the other hand, +comes in the final stages of processing. +In effect it says `typeset character number +so-and-so'. +\awp + +There is a construction to let a control sequence stand +for some character code: the \cstoidx chardef\par\ command. +The syntax of this is \label{chardef} +\begin{disp}\cs{chardef}\gram{control sequence}\gr{equals}\gram{number}, +\end{disp} +where the number can be an explicit +representation or a counter value, but it can also be +a character code +obtained using the left quote command (see above; +the full definition of \gr{number} is given in Chapter~\ref{number}). +In the plain format +the latter possibility is used in +definitions such as \begin{verbatim} +\chardef\%=`\% +\end{verbatim} +which could have been given equivalently as +\begin{verbatim} +\chardef\%=37 +\end{verbatim} +After this command, the control symbol \verb>\%> +used on its own is a synonym for \verb>\char37>, +that is, the command to typeset character~37 +(usually the per cent character). + +A control sequence that has been defined with a \cs{chardef} +command can also be used as a \gr{number}. +This fact is used in allocation commands such as +\cs{newbox} (see Chapters~\ref{number} and~\ref{alloc}). +Tokens defined with \cs{mathchardef} can also be used this +way. + +%\spoint Implicit character tokens: \cs{let} +\subsection{Implicit character tokens: \protect\cs{let}} + +Another construction defining a control sequence +\term character !implicit\par +to stand for (among other things) +a character is~\cs{let}\cstoidx let\par: +\begin{disp}\cs{let}\gr{control sequence}\gr{equals}\gr{token}\end{disp} +with a character token on the right hand side of the (optional) +equals sign. The result is called an implicit character token. +(See page~\pageref{let} for a further discussion of~\cs{let}.) + +In the +plain format there are for instance synonyms for +the open and close brace: +\begin{verbatim} +\let\bgroup={ \let\egroup=} +\end{verbatim} +The resulting control sequences are called `implicit braces' +(see Chapter~\ref{group}). + +Assigning characters by \cs{let} +is different from defining control sequences by \cs{chardef}, +in the sense that \cs{let} +makes the control sequence stand for the combination +of a character code and category code. + +As an example +\begin{verbatim} +\catcode`|=2 % make the bar an end of group +\let\b=| % make \b a bar character +{\def\m{...}\b \m +\end{verbatim} +gives an `undefined control sequence \cs{m}' +because the \cs{b} closed the group inside which \cs{m} +was defined. On the other hand, +\begin{verbatim} +\let\b=| % make \b a bar character +\catcode`|=2 % make the bar character end of group +{\def\m{...}\b \m +\end{verbatim} +leaves one group open, and it prints a vertical bar +(or whatever is in position 124 of the current font). +The first of these examples +implies that even when the braces have been redefined +(for instance into active characters for macros that +format C code) the beginning-of-group and end-of-group +functionality is available through the control sequences +\cs{bgroup} and~\cs{egroup}. + +Here is +another example to show +that implicit character tokens are hard to distinguish +from real character tokens. After the above sequence +\begin{verbatim} +\catcode`|=2 \let\b=| +\end{verbatim} +the tests \begin{verbatim} +\if\b| +\end{verbatim} +and \begin{verbatim} +\ifcat\b} +\end{verbatim} +are both true. + +Yet another example can be found in the plain format: +the commands +\begin{verbatim} +\let\sp=^ \let\sb=_ +\end{verbatim} +allow people without an +underscore or circumflex on their keyboard to +make sub- and superscripts in mathematics. +For instance: +\begin{disp}\verb>x\sp2\sb{ij}>\quad gives\quad $x\sp2\sb{ij}$\end{disp} +If a person typing in the format itself does not have +these keys, some further tricks are needed:\label{spsb:truc} +\begin{verbatim} +{\lccode`,=94 \lccode`.=95 \catcode`,=7 \catcode`.=8 +\lowercase{\global\let\sp=, \global\let\sb=.}} +\end{verbatim} +will do the job; see below for an explanation of lowercase codes. +The \verb>^^> method as it was in \TeX\ version~2 +(see page~\pageref{hathat}) cannot be used here, +as it would require typing two characters that can ordinarily +not be input. +With the extension in \TeX\ version~3 it would also be possible +to write \begin{verbatim} +{\catcode`\,=7 +\global\let\sp=,,5e \global\let\sb=,,5f} +\end{verbatim} +denoting the codes 94 and 95 hexadecimally. + +Finding out just what a control sequence has been defined to be with +\cs{let} can be done using \cs{meaning}: +the sequence \begin{verbatim} +\let\x=3 \meaning\x +\end{verbatim} +gives +`\n{the character 3}'.\awp + +%\point Accents +\section{Accents} + +Accents can be placed by the +\gr{horizontal command}~\cstoidx accent\par\term accents\par +\label{character}: +\begin{disp}\cs{accent}\gr{8-bit number}\gr{optional assignments}% + \gr{character}\end{disp} +where \gr{character} is a character of category 11 or~12, + a~\cs{char}\gr{8-bit number} command, +or a~\cs{chardef} token. If none of these +four types of \gr{character} follows, the accent is taken to be a +\cs{char} command itself; this gives an accent `suspended +in mid-air'. Otherwise the accent is placed +on top of the following character. +Font changes between the accent and the character can be effected +by the \gr{optional assignments}. + +An unpleasant implication of the fact that an \cs{accent} command +has to be followed by a \gr{character} is that it is not +possible to place an accent on a ligature, or +two accents on top of each other. +In some languages, such as Hindi or Vietnamese, +such double accents do occur. +Positioning accents on top of each other is possible, +however, in math mode. + +The width of a character with an accent is the same as that of +the unaccented character. \TeX\ assumes that the +accent as it appears in the font file +is properly positioned for a character that is as high +as the x-height of the font; for characters with other heights +it correspondingly lowers or raises the accent. + +No genuine under-accents exist in \TeX. They are +implemented as low placed over-accents. A~way of handling +them more correctly would be to write a macro that +measures the following character, and raises or drops +the accent accordingly. +The cedilla macro, \cs{c}\cstoidx c\par, +in plain \TeX\ does something along these lines. However, +it does not drop the accent for characters with descenders. + +The horizontal positioning of an accent is controlled by +\cs{fontdimen1}, slant per point. Kerns are used +for the horizontal movement. Note that, although they +are inserted automatically, these kerns are classified +as {\italic explicit\/} kerns. Therefore they inhibit hyphenation +in the parts of the word before and after the kern. + +As an example of kerning for accents, +here follows the dump of a horizontal list. +\message{maybe italic correction for extra line} +\begin{verbatim} +\setbox0=\hbox{\it \`l} +\showbox0 +\end{verbatim} +gives\begin{verbatim} +\hbox(9.58334+0.0)x2.55554 +.\kern -0.61803 (for accent) +.\hbox(6.94444+0.0)x5.11108, shifted -2.6389 +..\tenit ^^R +.\kern -4.49306 (for accent) +.\tenit l +\end{verbatim} +Note that the accent is placed first, so afterwards the italic +correction of the last character is still available. +\awp + +%\point Testing characters +\section{Testing characters} + +Equality of character codes is tested by \cs{if}: +\begin{disp}\cs{if}\gr{token$_1$}\gr{token$_2$}\end{disp} +Tokens following this conditional are expanded until two +unexpandable tokens are left. The condition is then true +if those tokens are character tokens with the same character +code, regardless of category code. + +An unexpandable control +sequence is considered to have character code 256 and +category code~16 (so that it is unequal to anything except +another control sequence), except in the case +where it had been \cs{let} to a non-active character token. +In that case it is considered to have the character code +and category code of that character. This was mentioned above. + +The test \cs{ifcat} for category codes was mentioned +in Chapter~\ref{mouth}; the test +\begin{disp}\cs{ifx}\gr{token$_1$}\gr{token$_2$}\end{disp} +can be used to test for category code and character code +simultaneously. +The tokens following this test are not expanded. +However, if they are macros, \TeX\ +tests their expansions for equality. + +Quantities defined by \cs{chardef} can be tested with +\cs{ifnum}: +\begin{verbatim} +\chardef\a=`x \chardef\b=`y \ifnum\a=\b % is false +\end{verbatim} +based on the fact (see Chapter~\ref{number}) that +\gr{chardef token}s can be used as numbers. + +%\point Uppercase and lowercase +\section{Uppercase and lowercase} + +%\spoint[uc/lc] Uppercase and lowercase codes +\subsection{Uppercase and lowercase codes} +\label{uc/lc} + +To each of the character codes correspond +\term uppercase\par\term lowercase\par +\cstoidx lccode\par\cstoidx uccode\par +an uppercase code and a lowercase code (for still more codes see below). +These can be assigned +by +\begin{Disp}\cs{uccode}\gram{number}\gr{equals}\gram{number}\end{Disp} +and +\begin{Disp}\cs{lccode}\gram{number}\gr{equals}\gram{number}.\end{Disp} +In \IniTeX\ codes \verb-`a..`z-, \verb-`A..`Z- have uppercase code +\label{ini:uclc} +\verb-`A..`Z- and lowercase code \verb-`a..`z-. +All other character codes have both uppercase and lowercase +code zero. + +%\spoint[upcase] Uppercase and lowercase commands +\subsection{Uppercase and lowercase commands} +\label{upcase} + +The commands \verb-\uppercase{...}- and \verb-\lowercase{...}- +\cstoidx uppercase\par\cstoidx lowercase\par +go through their argument lists, replacing all character +codes of explicit character tokens +by their uppercase and lowercase code respectively +if these are non-zero, +without changing the category codes. +\awp + +The argument of \cs{uppercase} and \cs{lowercase} +is a \gr{general text}, which is defined as +\begin{Disp} \gr{general text} $\longrightarrow$ \gr{filler}\lb + \gr{balanced text}\gr{right brace}\end{Disp} +(for the definition of \gr{filler} see Chapter~\ref{gramm}) +meaning that the left brace can be implicit, but the closing +right brace must be an explicit character token with category +code~2. \TeX\ performs expansion to find the opening +brace. + +Uppercasing and lowercasing are executed in the execution processor; +they are not `macro expansion' activities +like \cs{number} or \cs{string}. +The sequence (attempting to produce~\cs{A}) +\begin{verbatim} +\expandafter\csname\uppercase{a}\endcsname +\end{verbatim} +gives an error (\TeX\ inserts an \cs{endcsname} before the +\cs{uppercase} because \cs{uppercase} is unexpandable), but +\begin{verbatim} +\uppercase{\csname a\endcsname} +\end{verbatim} +works. + +As an example of the correct use of \cs{uppercase}, here +is a macro that tests if a character is uppercase: +\begin{verbatim} +\def\ifIsUppercase#1{\uppercase{\if#1}#1} +\end{verbatim} +The same test can be +performed by \verb>\ifnum`#1=\uccode`#1>. + +Hyphenation of words starting with an uppercase character, +that is, a character not equal to its own \cs{lccode}, +is subject to the \cs{uchyph} parameter: if this +is positive, hyphenation of capitalized words is allowed. +See also Chapter~\ref{line:break}. + +%\spoint Uppercase and lowercase forms of keywords +\subsection{Uppercase and lowercase forms of keywords} + +Each character in \TeX\ keywords, such as \n{pt}, can be +given in uppercase or lowercase form. +For instance, \n{pT}, \n{Pt}, \n{pt}, and~\n{PT} all have +the same meaning. \TeX\ does not use +the \cs{uccode} and \cs{lccode} tables here to +determine the lowercase form. Instead it +converts uppercase characters to lowercase by adding~32 +\ldash the \ascii{} difference between uppercase and lowercase +characters \rdash to their character code. This has some implications +for implementations of \TeX\ for non-roman alphabets; +see page 370 of \TeXbook, \cite{Knuth:TeXbook}. + +%\spoint Creative use of \cs{uppercase} and \cs{lowercase} +\subsection{Creative use of \cs{uppercase} and \cs{lowercase}} + +The fact that \cs{uppercase} and \cs{lowercase} do not change +category codes can sometimes be used to create certain +character-code--category-code combinations that would +otherwise be difficult to produce. See for instance the +explanation of the \cs{newif} macro in Chapter~\ref{if}, +and another example on page~\pageref{spsb:truc}. + +For a slightly different application, consider the +problem (solved by Rainer Sch\"opf) of, +given a counter \verb-\newcount\mycount-, writing character +number \verb-\mycount- to the terminal. +Here is a solution: +%\begin{verbatim} +%\lccode`a=\mycount \chardef\terminal=16 +%\lowercase{\write\terminal{a}} +%\end{verbatim} +\begin{verbatim} +\lccode`a=\mycount \chardef\terminal=16 +\end{verbatim} +\awp +\begin{verbatim} +\lowercase{\write\terminal{a}} +\end{verbatim} +The \cs{lowercase} command effectively changes the +argument of the \cs{write} command from~`\n a' +into whatever it should be. + +%\point[codename] Codes of a character +\section{Codes of a character} +\label{codename} + +Each character code has a number of \gr{codename}s associated +\term codenames\par +with it. These are integers in various ranges that determine +how the character is treated in various contexts, or +how the occurrence of that character changes the workings +of \TeX\ in certain contexts. + +The code names are as follows: +\begin{description}\item [\cs{catcode}] +\gr{4-bit number} (0--15); the category to which a character belongs. +This is treated in Chapter~\ref{mouth}. +\item [\cs{mathcode}] +\gr{15-bit number} (0--\verb-"7FFF-) or \verb-"8000-; +determines how a character is treated +in math mode. See Chapter~\ref{mathchar}. +\item [\cs{delcode}] +\gr{27-bit number} (0--\n{\hex7$\,$FFF$\,$FFF}); +determines how a character is treated after +\cs{left} or \cs{right} in math mode. +See page~\pageref{delcodes}. +\item [\cs{sfcode}] +integer; determines how spacing is affected after this character. +See Chapter~\ref{space}. +\item [\cs{lccode}, \cs{uccode}] +\gr{8-bit number} (0-255); lowercase and +uppercase codes \rdash these were treated above. +\end{description} + +%\point Converting tokens into character strings +\section{Converting tokens into character strings} + +The command \cs{string} takes the next token and expands it +\cstoidx string\par +into a string of separate characters. Thus +\begin{verbatim} +\tt\string\control +\end{verbatim} +will give \cs{control} in the +output, and +\begin{verbatim} +\tt\string$ +\end{verbatim} +will give~\verb-$-, but, noting that the string +operation comes after the tokenizing, +\begin{verbatim} +\tt\string% +\end{verbatim} +will {\em not\/} give~\verb$%$, +because the comment +sign is removed by \TeX's input processor. +Therefore, this command will `string' the first token on the next line. + +The \cs{string} command is executed by the expansion processor, thus +it is expanded unless explicitly inhibited (see Chapter~\ref{expand}). + +%\spoint Output of control sequences +\subsection{Output of control sequences} + +In the above examples the typewriter font was selected, because +\cstoidx escapechar\par +the Computer Modern roman font does not have a backslash character. +\awp +However, +\TeX\ need not have used the backslash character to display +a control sequence: it uses character number \cs{escapechar}. +This same value is also used when a control sequence is +output with \cs{write}, \cs{message}, or \cs{errmessage}, +and it is used in the output of \cs{show}, \cs{showthe} and \cs{meaning}. +If \cs{escapechar} is negative or more than~255, +the escape character is not +output; the default value (set in \IniTeX) is~92, the number +of the backslash character. + +For use in a \cs{write} statement the \cs{string} can +in some circumstances be +replaced by \cs{noexpand} (see page~\pageref{expand:write}). + +%\spoint Category codes of a \cs{string} +\subsection{Category codes of a \cs{string}} + +The characters that are the result of a \cs{string} command have +category code~12, except for any spaces in +a stringed control sequence; +they have category code~10. Since inside a control +sequence there are no category codes, +any spaces resulting from \cs{string} are +of necessity only space {\em characters}, that is, +characters with code~32. +However, \TeX's input processor converts +all space tokens that have a character code other than~32 +into character tokens with character code~32, +so the chances are pretty slim that +`funny spaces' wind up in control sequences. + +Other commands with the same behaviour with respect to +category codes as \cs{string}, are +\cs{number}, +\cs{romannumeral}, \cs{jobname}, \cs{fontname}, \cs{meaning}, +and \cs{the}. + + + + +%%%% end of input file [char] + +%\InputFile:fontfam +%%%% this is input file [fontfam] +%\subject[font] Fonts +\endofchapter +\chapter{Fonts}\label{font} + +In text mode \TeX\ takes characters from a `current font'. +\term fonts\par +This chapter describes how fonts are identified to \TeX, +and what attributes a font can have. + +\begin{inventory} +\item [\cs{font}] + Declare the identifying control sequence of a font. + +\item [\cs{fontname}] + The external name of a font. + +\item [\cs{nullfont}] + Name of an empty font that \TeX\ uses in emergencies. + + +\item [\cs{hyphenchar}] + Number of the hyphen character of a font. + +\item [\cs{defaulthyphenchar}] + Value of \cs{hyphenchar} when a font is loaded. + Plain \TeX\ default:~\verb>`\->. + +\item [\cs{fontdimen}] + Access various parameters of fonts. + +\item [\cs{char47}] + Italic correction. + +\item [\cs{noboundary}] + Omit implicit boundary character. +\end{inventory} + +%\point Fonts +\section{Fonts} + +In \TeX\ terminology a font is the set of characters that +is contained in one external font file. +During processing, \TeX\ decides from +what font a character should be taken. This decision is +taken separately for text mode and math mode. + +When \TeX\ is processing ordinary text, characters are taken +from the `current font'. +External font file names are coupled to control sequences +by statements such as +\begin{verbatim} +\font\MyFont=myfont10 +\end{verbatim} +which makes \TeX\ load the file \n{myfont10.tfm}. +Switching the current font to the font described in that file +is then done by +\begin{verbatim} +\MyFont +\end{verbatim} +The status of the current font +can be queried: the sequence \begin{verbatim} +\the\font +\end{verbatim} +produces the control sequence for the current font. + +Math mode completely ignores the current font. Instead +it looks at the `current family', which can contain +three fonts: one for text style, one for script style, +and one for scriptscript style. This is treated +in Chapter~\ref{mathchar}. +\awp + +See \cite{S} for a consistent terminology of fonts and typefaces. + +With `virtual fonts' (see~\cite{K:virt}) it is possible that +what looks like one font to \TeX\ resides in more than +one physical font file. +\alt +See further page~\pageref{virtual:fonts}. + +%\point Font declaration +\section{Font declaration} + +Somewhere during a run of \TeX\ or \IniTeX\ +\cstoidx font\par +the coupling between an internal identifying control sequence +and the external file name of a font has to be made. +The syntax of the command for this is +\begin{disp}\cs{font}\gr{control sequence}\gr{equals}% +\gr{file name}\gr{at clause}\end{disp} +where +\begin{disp}\gr{at clause} $\longrightarrow$ \n{at} \gr{dimen} +$|$ \n{scaled} \gr{number} $|$ \gr{optional spaces}\end{disp} +Font declarations are local to a group. + +By the \gr{at clause} the user specifies that some +magnified version of the font is wanted. The \gr{at clause} comes +in two forms: if the font is given \n{scaled}~{\italic f\/} \TeX\ +multiplies all its font dimensions for that font by~$f/1000$; +if the font +has a design size~{\italic d\/}\n{pt} and +the \gr{at clause} is \n{at}~{\italic p\/}\n{pt} +\TeX\ multiplies all font data by~$p/d$. +The presence of an \gr{at clause} makes no difference for +the external font file (the \n{.tfm} file) +that \TeX\ reads for the font; it just multiplies +the font dimensions by a constant. + + +After such a font declaration, using the defined control sequence +will set the current font to the font of the +control sequence. + +%\spoint Fonts and \n{tfm} files +\subsection{Fonts and \n{tfm} files} + +The external file needed for the font is a \n{tfm} +(\TeX\ font metrics) file, +which is taken independent of any \gr{at clause} +in the \cs{font} declaration. If the \n{tfm} +file has been loaded already (for instance by \IniTeX\ +when it constructed the format), +an assignment of that font file can be reexecuted +without needing recourse to the \n{tfm} file. + +Font design sizes are given in the font metrics files. +The \n{cmr10} font, for instance, has a design size +of 10~point. However, there is not much in the font +that actually has a size of 10~points: the opening and closing +parentheses are two examples, but capital +letters are considerably smaller. + +%\spoint Querying the current font and font names +\subsection{Querying the current font and font names} + +It was already mentioned above that the control sequence +which set the current font can be retrieved by the +command \verb>\the\font>. This is a special case of +\begin{Disp}\cs{the}\gr{font}\end{Disp} where +\begin{disp}\gr{font} $\longrightarrow$ +\cs{font} $|$ \gr{fontdef token} $|$ \gr{family member}\nl +\gr{family member} $\longrightarrow$ +\gr{font range}\gr{4-bit number}\nl +\gr{font range} $\longrightarrow$ +\cs{textfont} $|$ \cs{scriptfont} $|$ \cs{scriptscriptfont}\end{disp} +\awp +A \gr{fontdef token} is a control sequence defined by \cs{font}, +or the predefined control sequence \cs{nullfont}. +The concept of \gr{family member} is only +relevant in math mode. + +Also, the +\cstoidx fontname\par +external name of fonts can be retrieved: +\begin{Disp}\cs{fontname}\gr{font}\end{Disp} +gives a sequence of character tokens of category~12 +(but space characters get category~10) that spells the font file +name, plus an \gr{at clause} if applicable. + +\begin{example} After +\begin{verbatim} +\font\tenroman=cmr10 \tenroman +\end{verbatim} +the calls +\verb>\the\font> and \verb>\the\tenroman> both give \cs{tenroman}. +The call \verb>\fontname\tenroman> gives \n{cmr10}. +\end{example} + +%\spoint \cs{nullfont} +\subsection{\cs{nullfont}} + +\TeX\ always knows a font that has no characters: the \csidx{nullfont}. +If no font has been specified, or if in math mode a family member +is needed that has not been specified, +\TeX\ will take its characters from the nullfont. +This control sequence qualifies as a \gr{fontdef token}: +it acts like any other control sequence that stands for a font; +it just does not have an associated \n{tfm} file. + +%\point Font information +\section{Font information} + +During a run of \TeX\ the main information needed about the +\term \n{tfm} files\par +font consists of the dimensions of the characters. +\TeX\ finds these in the font metrics files, which usually have +extension \n{.tfm}. Such files +contain \begin{itemize} \item global information: the \cs{fontdimen} +parameters, and some other information, +\item dimensions and the italic corrections of characters, and +\altt +\item ligature and kerning programs for characters. + \end{itemize} +Also, the design size of a font is specified in the \n{tfm} file; +see above. The definition of the \n{tfm} format can be found +in~\cite{Knuth:TeXprogram}. + +%\spoint[font:dims] Font dimensions +\subsection{Font dimensions} +\label{font:dims} + +Text fonts need to have at least seven \csidx{fontdimen} parameters +(but \TeX\ will take zero for unspecified parameters); +\term font! dimensions\par +math symbol and math extension fonts have more +(see page~\pageref{fam23:fontdims}). +For text fonts the minimal set of seven comprises the following: +\begin{enumerate} \item the slant per point; this dimension is used + for the proper horizontal positioning of accents; +\awp +\item the interword space: this is used unless the user + specifies an explicit \cs{spaceskip}; + see Chapter~\ref{space}; +\item interword stretch: the stretch component of the interword + space; +\item interword shrink: the shrink component of + the interword space; +\item the x-height: the value of + the \gr{internal unit} \n{ex}, which is usually about the + height of the lowercase letter~`x'; +\item the quad width: + the value of the \gr{internal unit} \n{em}, which is + approximately the width of the capital letter~`M'; and +\item the extra space: the space added to the interword space +at the end of sentences (that is, when \cs{spacefactor}${}\geq2000$) +unless the user specifies an explicit \cs{x\-space\-skip}. +\end{enumerate} + +Parameters 1 and~5 are purely information about the font +and there is no point in varying them. +The values of other parameters can be changed in order to +adjust spacing; see Chapter~\ref{space} for examples +of changing parameters 2, 3, 4, and~7. + +Font dimensions can be altered in a \gr{font assignment}, +which is a \gr{global assignment} (see page~\pageref{global:assign}): +\begin{Disp}\cs{fontdimen}\gr{number}\gr{font}\gr{equals}\gr{dimen} +\end{Disp} See above for the definition of \gr{font}. + +%\spoint Kerning +\subsection{Kerning} + +Some combinations of characters should be moved closer +\term kerning\par +together than would be the case if their bounding boxes +were to be just abutted. This fine spacing is called kerning, +and a proper kerning is as essential to a font as the +design of the letter shapes. + +Consider as an example\message{Kerning!} +\begin{Disp} `Vo' versus the unkerned variant `V\hbox{}o'\end{Disp} + +Kerning in \TeX\ is controlled by information in the +\n{tfm} file, and is therefore outside the influence of the +user. The \n{tfm} file can be edited, however (see Chapter~\ref{TeXcomm}). + +The \cs{kern} command has (almost) nothing to do with the +phenomenon of kerning; it is explained in Chapter~\ref{glue}. + +%\spoint Italic correction +\subsection{Italic correction} + +The primitive control symbol \verb-\/- inserts the `italic +\term italic correction\par\cstoidx /\par +correction' of the previous character or ligature. +Such a correction may be necessary owing to the definition +of the `bounding box' of a character. This box always +has vertical sides, and the width of the character as \TeX\ +perceives it is the distance between these sides. +However, in order to achieve proper spacing for slanted or +italic typefaces, characters may very well project outside their +bounding boxes. The italic correction is then needed if +such an overhanging character is followed by a +character from a non-slanting typeface. +\awp + +Compare for instance\message{Visible italic correction!} +\begin{Disp} `{\italic\TeX} has' +to `{\italic\TeX\/} has', +\end{Disp} where the second version was typed as +\begin{verbatim} +{\italic\TeX\/} has +\end{verbatim} + +The size of the italic correction of each character +is determined by font information +in the font metrics file; for the Computer Modern fonts it is +approximately half the `overhang' of the characters; +see~\cite{K:partE}. +Italic correction is not the same as \cs{fontdimen1}, slant +per point. That font dimension is used only for positioning +accents on top of characters. + +An italic correction can only be inserted if the previous item +processed +by \TeX\ was a character or ligature. Thus the +following solution for roman text inside an italic passage +does not work: +\begin{verbatim} +{\italic Some text {\/\roman not} emphasized} +\end{verbatim} +The italic correction has no effect here, +because the previous item is glue. + +%\spoint Ligatures +\subsection{Ligatures} + +Replacement of character sequences by ligatures is controlled +\term ligatures\par +by information in the \n{tfm} file of a font. +Ligatures are formed from \gr{character} commands: +sequences such as \n{fi} are replaced by `fi' in some fonts. + +Other ligatures traditionally in use are +between \n{ff}, \n{ffi}, \n{fl}, and \n{ffl}; +in some older works \n{ft} and \n{st} can be found, +and similarly to the \n{fl} ligature \n{fk} and \n{fb} +can also occur. + +Ligatures in \TeX\ can be formed between explicit character +tokens, \cs{char} commands, and \gr{chardef token}s. +For example, +the sequence \verb-\char`f\char`i- is replaced by the +`fi' ligature, if such a ligature is part of the font. + +Unwanted ligatures can be suppressed in a number of ways: +the unwanted ligature `\hbox{halflife}' can +for instance be prevented by +\begin{disp} \verb>half{}life>, \verb>half{l}ife>, \verb>half\/life>, + or \verb>half\hbox{}life>\end{disp} +but the solution using italic correction is not equivalent +to the others. + +%\spoint Boundary ligatures +\subsection{Boundary ligatures} + +Each word is surrounded by a left and a right +boundary character (\TeX3 only). +This makes phenomena possible +such as the two different sigmas in Greek: +one at the end of a word, and one for every other position. +This can be realized through a ligature with the +boundary character. A~\csidx{noboundary} command immediately +before or after a word suppresses the boundary character +at that place. + +In general, the ligature mechanism has become more complicated +with the transition to \TeX\ version~3; see~\cite{K:TeX23}. + +%%%% end of input file [fontfam] + +%\InputFile:boxes +%%%% this is input file [boxes] +%\tracingmacros=2 \tracingcommands\tracingmacros +%\subject[boxes] Boxes +\endofchapter +\chapter{Boxes}\label{boxes} + +The horizontal and vertical boxes of \TeX\ are containers for +\term box\par +pieces of horizontal and vertical lists. +Boxes can be stored in box registers. +This chapter treats box registers and such +aspects of boxes as their dimensions, and the way their components +are placed relative to each other. + +\begin{inventory} +\item [\cs{hbox}] + Construct a horizontal box. +\item [\cs{vbox}] + Construct a vertical box with reference point of the last item. +\item [\cs{vtop}] + Construct a vertical box with reference point of the first item. +\item [\cs{vcenter}] + Construct a vertical box vertically centred + on the math axis; this command can only be used in math mode. + +\item [\cs{vsplit}] + Split off the top part of a vertical box. + +\item [\cs{box}] + Use a box register, emptying it. + +\item [\cs{setbox}] + Assign a box to a box register. + +\item [\cs{copy}] + Use a box register, but retain the contents. + +\item [\cs{ifhbox \cs{ifvbox}}] +\mdqon + Test whether a box register contains a horizontal/""vertical box. +\mdqoff + +\item [\cs{ifvoid}] + Test whether a box register is empty. + + +\item [\cs{newbox}] + Allocate a new box register. + +\item [\cs{unhbox \cs{unvbox}}] + Unpack a box register containing a horizontal/vertical box, + adding the contents to the current horizontal/vertical list, + and emptying the register. + +\item [\cs{unhcopy \cs{unvcopy}}] + The same as \cs{unhbox}$\,$/$\,$\cs{unvbox}, + but do not empty the register. + +\item [\cs{ht \cs{dp} \cs{wd}}] + Height/depth/width of the box in a box register. + +\item [\cs{boxmaxdepth}] + Maximum allowed depth of boxes. + Plain \TeX\ default:~\cs{maxdimen}. + +\item [\cs{splitmaxdepth}] + Maximum allowed depth of boxes generated by \cs{vsplit}. + +\item [\cs{badness}] + Badness of the most recently constructed box. + +\item [\cs{hfuzz \cs{vfuzz}}] + Excess size that \TeX\ tolerates before it considers +\mdqon + a horizontal/""vertical box overfull. +\mdqoff + +\item [\cs{hbadness \cs{vbadness}}] + Amount of tolerance before \TeX\ reports an underfull +\mdqon + or overfull horizontal/""vertical box. +\mdqoff + +\item [\cs{overfullrule}] + Width of the rule that is printed to indicate + overfull horizontal boxes. + + +\item [\cs{hsize}] + Line width used for text typesetting inside a vertical box. +\awp + +\item [\cs{vsize}] + Height of the page box. + + +\item [\cs{lastbox}] + Register containing the last item added to the current list, + if this was a box. + +\item [\cs{raise \cs{lower}}] + Adjust vertical positioning of a box in horizontal mode. + +\item [\cs{moveleft \cs{moveright}}] + Adjust horizontal positioning of a box in vertical mode. + +\item [\cs{everyhbox \cs{everyvbox}}] +\mdqon + Token list inserted at the start of a horizontal/""vertical box. +\mdqoff + +\end{inventory} + +%\point Boxes +\section{Boxes} + +In this chapter we shall look at boxes. Boxes are containers +for pieces of horizontal or vertical lists. +Boxes that are needed more than once can be stored in box registers. + +When \TeX\ expects a \gr{box}, any of the following forms +is admissible: +\begin{itemize} +\item \cs{hbox}\gr{box specification}\lb\gr{horizontal material}\rb +\item \cs{vbox}\gr{box specification}\lb\gr{vertical material}\rb +\item \cs{vtop}\gr{box specification}\lb\gr{vertical material}\rb +\item \cs{box}\gr{8-bit number} +\item \cs{copy}\gr{8-bit number} +\item \cs{vsplit}\gr{8-bit number}\n{to}\gr{dimen} +\item \cs{lastbox} +\end{itemize} +A \gr{box specification} is defined as\label{box:spec} +\begin{disp}\gr{box specification} $\longrightarrow$ \gr{filler} +\nl\indent$|$ \n{to} \gr{dimen}\gr{filler} + $|$ \n{spread} \gr{dimen}\gr{filler} +\end{disp} +An \gr{8-bit number} is a number in the range~0--255. + +The braces surrounding box material define a group; +they can be explicit characters +of categories 1 and~2 respectively, +or control sequences \cs{let} to such characters; +see also below. + + +A \gr{box} can in general be used in horizontal, vertical, +and math mode, but see below for the \cs{lastbox}. +The connection between +boxes and modes is explored further in Chapter~\ref{hvmode}. + +The box produced by \cs{vcenter} \ldash a command that is allowed only in +math mode \rdash is not a \gr{box}. For instance, +it can not be assigned with \verb=\setbox=; see further +Chapter~\ref{math}. + +The \cs{vsplit} operation is treated in Chapter~\ref{page:break}. + +%\point Box registers +\section{Box registers} + +There are 256 box registers, numbered 0--255. +\term box! registers\par +Either a box register is empty (`void'), or it contains a horizontal +or vertical box. +This section discusses specifically box {\em registers}; +the sizes of boxes, and the way material is arranged inside them, +is treated below. +\awp + +%\spoint Allocation: \cs{newbox} +\subsection{Allocation: \cs{newbox}} + +The plain \TeX\ \csidx{newbox} macro allocates an unused +box register: +\begin{verbatim} +\newbox\MyBox +\end{verbatim} +after which one can say +\begin{verbatim} +\setbox\MyBox=... +\end{verbatim} +or \begin{verbatim} +\box\MyBox +\end{verbatim} +and so on. +Subsequent calls to this macro give subsequent box numbers; +this way macro collections can allocate their own boxes +without fear of collision with other macros. + +The number of the box is assigned by \cs{chardef} +(see Chapter~\ref{alloc}). +This implies that \cs{MyBox} is equivalent to, +and can be used as, a~\gr{number}. +The control sequence +\altt +\cs{newbox} is an \cs{outer} macro. +Newly allocated box registers are initially empty. + + +\subsection{Usage: \cs{setbox}, \cs{box}, \cs{copy}} + +A~register is filled by assigning a \gr{box} +\cstoidx setbox\par +to it: +\begin{Disp}\verb>\setbox>\gr{number}\gr{equals}\gr{box}\end{Disp} +For example, the \gr{box} can be explicit +\begin{Disp}\verb>\setbox37=\hbox{...}>\quad or\quad \verb>\setbox37=\vbox{...}> +\end{Disp} +or it can be a box register: +\begin{verbatim} +\setbox37=\box38 +\end{verbatim} +Usually, box numbers will have been assigned by a \cs{newbox} +command. + +The box in a box register is appended +by the commands \cs{box} and~\cs{copy} +to whatever list \TeX\ is building: the call +\begin{verbatim} +\box38 +\end{verbatim} +appends box~38. +To save memory space, box registers become empty by using them: +\TeX\ assumes that after you have inserted a box by +calling \csidx{box}$nn$ in some mode, you do not need the +contents of that register any more and empties it. +In case you {\em do\/} need the contents of +a box register more than once, +you can \csidx{copy} it. Calling \cs{copy}$nn$ is +equivalent to \cs{box}$nn$ in all respects except that +the register is not cleared. + +It is possible to unwrap the contents of a box register +by `unboxing' it using the commands \cs{unhbox} and \cs{unvbox}, +and their copying versions \cs{unhcopy} and \cs{unvcopy}. +Whereas a box can be used in any mode, the +unboxing operations can only be used in the appropriate mode, +since in effect they contribute a partial +horizontal or vertical list (see also Chapter~\ref{hvmode}). +See below for more information on unboxing registers. +\awp + +%\spoint Testing: \cs{ifvoid}, \cs{ifhbox}, \cs{ifvbox} +\subsection{Testing: \cs{ifvoid}, \cs{ifhbox}, \cs{ifvbox}} + +Box +registers can be tested for their contents: +\begin{disp}\cs{ifvoid}\gr{number}\end{disp} +is true if the box register is empty. +Note that an empty, or `void', +box register is not the same as a register containing an empty box. +An empty box is still either a horizontal or a vertical box; +a~void register can be used as both. + +The test +\begin{disp}\cs{ifhbox}\gr{number}\end{disp} +is true if the box register contains a horizontal box; +\begin{disp}\cs{ifvbox}\gr{number}\end{disp} +is true if the box register contains a vertical box. +Both tests are false for void registers. + +%\spoint[lastbox] The \cs{lastbox} +\subsection{The \cs{lastbox}} +\label{lastbox} + +When \TeX\ has built a partial list, the last box in this +list is accessible as the \csidx{lastbox}. This behaves +like a box register, so you can remove the last box from the +list by assigning the \cs{lastbox} to some box register. +If the last item on the current list is not a box, +the \cs{lastbox} acts like a void box register. +It is not possible to get hold of the last box +in the case of the main vertical list. +The \cs{lastbox} is then always void. + +As an example, the statement \begin{verbatim} +{\setbox0=\lastbox} +\end{verbatim} +removes +the last box from the current list, assigning it to box +register~0. Since this assignment occurs inside a group, +the register is cleared at the end of the group. +At the start of a paragraph this can be used to remove the +indentation box (see Chapter~\ref{par:start}). +Another example of \cs{lastbox} can be found on page~\pageref{varioset}. + +Because the \verb-\lastbox- is always empty in external vertical mode, +it is not possible to get hold of boxes that have been +added to the page. However, it is possible to dissect +the page once it is in \cs{box255}, for instance doing +\begin{verbatim} +\vbox{\unvbox255{\setbox0=\lastbox}} +\end{verbatim} +inside the output routine. + +If boxes in vertical mode have been shifted by \cs{moveright} +or \cs{moveleft}, or if boxes in horizontal mode have +been raised by \cs{raise} or lowered by \cs{lower}, +any information about this +displacement due to such a command is lost when +the \cs{lastbox} is taken from the list. +\awp + +%\point Natural dimensions of boxes +\section{Natural dimensions of boxes} + +%\spoint Dimensions of created horizontal boxes +\subsection{Dimensions of created horizontal boxes} + +Inside an \csidx{hbox} all constituents are lined up next to each other, +\term box! dimensions\par +with their reference points on the baseline of the box, +unless they are moved explicitly in the vertical direction +by \cs{lower} or~\cs{raise}. + +The resulting width of the box is the sum of the widths +of the components. Thus the width of +\begin{verbatim} +\hbox{\hskip1cm} +\end{verbatim} +is positive, and the width of +\begin{verbatim} +\hbox{\hskip-1cm} +\end{verbatim} +is negative. By way of example, +\begin{disp}\verb>a\hbox{\kern-1em b}-->\end{disp} +gives as output +\begin{disp}\leavevmode\hphantom{b}a\hbox{\kern-1em b}--\end{disp} +\message{check align input/output} +which shows that a horizontal box can have negative +width. + +The height and depth of an \cs{hbox} are the +maximum amount that constituent boxes project above and +below the baseline of the box. They are non-negative when the +box is created. + +The commands \cs{lower} and \cs{raise} are the only possibilities +for vertical movement inside an \cs{hbox} (other than +including a \cs{vbox} inside the \cs{hbox}, of course); +a~\gr{vertical command} \ldash such as \cs{vskip} \rdash +is not allowed in a horizontal box, and +\cs{par}, although allowed, +does not do anything inside a horizontal box. + +%\spoint Dimensions of created vertical boxes +\subsection{Dimensions of created vertical boxes} + +Inside a \csidx{vbox} vertical material is lined up with the +\cstoidx vtop\par +reference points on the vertical line through the reference +point of the box, +unless components are moved explicitly in the horizontal direction +by \csidx{moveleft} or~\csidx{moveright}. + +The reference point of a vertical box +is always located at the left boundary of the box. +The width of a vertical box +is then the maximal amount that any material in the +box sticks to the right of the reference point. +Material to the left of the reference point is +not taken into account in the width. +Thus the result of +\begin{disp}\verb>a\vbox{\hbox{\kern-1em b}}-->\end{disp} +is +\begin{disp}\leavevmode\hphantom{b}a\vbox{\hbox{\kern-1em b}}--\end{disp} +This should be contrasted with the above example. + + +The calculation of height and depth is different +for vertical boxes constructed by \cs{vbox} and \cs{vtop}. +The ground rule is that +\awp +a \cs{vbox} has a reference point that lies on +the baseline of its last component, +and a \cs{vtop} has its reference point on the baseline of the +first component. +In general, the depth (height) of a \cs{vbox} (\cs{vtop}) +\alt +can be non-zero if the last (first) item is a box or rule. + +The height of a \cs{vbox} is then the sum of the heights and +depths of all components except the last, plus the height +of that last component; the depth of the \cs{vbox} is the +depth of its last component. +The depth of a \cs{vtop} +is the sum of the depth of the first component and the heights +and depths of all subsequent material; its height is the +height of the first component. + +However, the actual rules are a bit +more complicated when the first component of a \cs{vtop} +or the last component of a \cs{vbox} is not a box or rule. +If the last component of a \cs{vbox} is a kern or a glue, +the depth of that box is zero; a \cs{vtop}'s +height is zero +unless its first component is a box or rule. +\altt +(Note the asymmetry in these definitions; see below for +an example illustrating this.) +The depth of a \cs{vtop}, then, is equal to the total +height plus depth of all enclosed material minus +the height of the \cs{vtop}. + +There is a limit on the depth of vertical boxes: +if the depth of a \cs{vbox} or \cs{vtop} +calculated by the above rules would exceed +\cstoidx boxmaxdepth\par, +the reference point of the box +is moved down by the excess amount. +More precisely, the excess depth is added to the +natural height of the box. If the box had a \n{to} or +\n{spread} specification, any glue is set anew to take +the new height into account. + +Ordinarily, +\cs{boxmaxdepth} is set to the maximum dimension +possible in \TeX. It is for instance reduced during some of +the calculations in the plain \TeX\ output routine; +see Chapter~\ref{output}. + +%\spoint Examples +\subsection{Examples} + +Horizontal boxes are relatively straightforward. Their width is the +distance between the `beginning' and the `end' of the +box, +and consequently the width is not necessarily positive. +With +\begin{verbatim} +\setbox0=\hbox{aa} \setbox1=\hbox{\copy0 \hskip-\wd0} +\end{verbatim} +the \cs{box1} has width zero; +\begin{Disp} \verb-/\box1/-\quad gives\quad +`{\setbox0=\hbox{aa}\setbox1=\hbox{\copy0 \hskip-\wd0}/\box1/}\kern.75em' +\end{Disp} +The height and depth of a horizontal box cannot be negative: in +\begin{verbatim} +\setbox0=\hbox{\vrule height 5pt depth 5pt} +\setbox1=\hbox{\raise 10pt \box0} +\end{verbatim} +the \cs{box1} has depth \n{0pt} and height~\n{15pt} + +Vertical boxes are more troublesome than horizontal boxes. +Let us first treat their width. +After \begin{verbatim} +\setbox0=\hbox{\hskip 10pt} +\end{verbatim} +the box in the +\cs{box0} register has a width of \n{10pt}. Defining +\begin{verbatim} +\setbox1=\vbox{\moveleft 5pt \copy0} +\end{verbatim} +\awp +the \cs{box1} will have width \n{5pt}; material to the +left of the reference point is not accounted for in the +width of a vertical box. With +\begin{verbatim} +\setbox2=\vbox{\moveright 5pt \copy0} +\end{verbatim} +the \cs{box2} will have width \n{15pt}. + +The depth of a \cs{vbox} is the depth of the last item if +that is a box, so +\begin{verbatim} +\vbox{\vskip 5pt \hbox{\vrule height 5pt depth 5pt}} +\end{verbatim} +has height \n{10pt} and depth \n{5pt}, +and \begin{verbatim} +\vbox{\vskip -5pt \hbox{\vrule height 5pt depth 5pt}} +\end{verbatim} +has height \n{0pt} and depth~\n{5pt}. +With a glue or kern as the last item in the box, the resulting depth +is zero, so +\begin{verbatim} +\vbox{\hbox{\vrule height 5pt depth 5pt}\vskip 5pt} +\end{verbatim} +has height \n{15pt} and depth~\n{0pt}; +\begin{verbatim} +\vbox{\hbox{\vrule height 5pt depth 5pt}\vskip -5pt} +\end{verbatim} +has height \n{5pt} and depth~\n{0pt}. + +The height of a \cs{vtop} behaves (almost) the same with respect to +the first item of the box, as the depth of a \cs{vbox} does +with respect to the last item. Repeating the above examples with +a \cs{vtop} gives the following: +\begin{verbatim} +\vtop{\vskip 5pt \hbox{\vrule height 5pt depth 5pt}} +\end{verbatim} +has height \n{0pt} and depth \n{15pt}, +and \begin{verbatim} +\vtop{\vskip -5pt \hbox{\vrule height 5pt depth 5pt}} +\end{verbatim} +has height \n{0pt} and depth~\n{5pt}; +\begin{verbatim} +\vtop{\hbox{\vrule height 5pt depth 5pt} \vskip 5pt} +\end{verbatim} +has height \n{5pt} and depth~\n{10pt}, and +\begin{verbatim} +\vtop{\hbox{\vrule height 5pt depth 5pt} \vskip -5pt} +\end{verbatim} +has height \n{5pt} and depth~\n{0pt}. + +%\point More about box dimensions +\section{More about box dimensions} + +%\spoint Predetermined dimensions +\subsection{Predetermined dimensions} + +The size of a box can be specified in advance +with a \gr{box specification}; see above for the syntax. +Any glue +in the box is then set in order to reach the required size. +Prescribing the size of the box is done by +\begin{disp}\cs{hbox} \n{to} \gr{dimen} \n{\lb...\rb}, + \cs{vbox} \n{to} \gr{dimen} \n{\lb...\rb}\end{disp} +\awp +If stretchable or shrinkable glue is present in the box, +it is stretched or shrunk in order to give the box the +specified size. Associated with this glue setting is a badness value +(see Chapter~\ref{glue}). If no stretch or shrink \ldash whichever +is necessary \rdash is present, the resulting box will be underfull +or overfull respectively. Error reporting for over/underfull +boxes is treated below. + +Another command to let a box have a size other than +the natural size is +\begin{disp}\cs{hbox} \n{spread} \gr{dimen} \n{\lb...\rb}, + \cs{vbox} \n{spread} \gr{dimen} \n{\lb...\rb}\end{disp} +which tells \TeX\ to set the glue in such a way that +the size of the box is a specified amount more than the +natural size. + +Box specifications for \cs{vtop} vertical boxes are +somewhat difficult to interpret. \TeX\ constructs a \cs{vtop} +by first making a \cs{vbox}, including +glue settings induced by a \gr{box specification}; +then it computes the height and depth by the above rules. +Glue setting is described in Chapter~\ref{glue}. + +%\spoint Changes to box dimensions +\subsection{Changes to box dimensions} + +The dimensions of a box register are accessible by the +commands \csidx{ht}, \csidx{dp}, and~\csidx{wd}; +for instance \cs{dp13} gives the depth of box~13. +However, not only can boxes be measured this way; +by assigning values to these +dimensions \TeX\ can even be fooled into thinking that +a box has a size different from its actual. +However, changing the dimensions of a box does not change +anything about the contents; in particular it does not +change the way the glue is set. + + +Various formats use this in `smash' macros: the macro defined by +\cstoidx smash\par +\begin{verbatim} +\def\smash#1{{\setbox0=\hbox{#1}\dp0=0pt \ht0=0pt \box0\relax}} +\end{verbatim} +places its argument but annihilates its height and depth; +\altt +that is, the output does show the whole box, but further calculations +by \TeX\ act as if the height and depth were zero. + +Box dimensions can be changed only by setting them. +They are \gr{box dimen}s, which can only be set +in a \gr{box size assignment}, and not, for instance +changed with \cs{advance}. + +Note that a \gr{box size assignment} is a \gr{global assignment}: +its effect transcends any groups in which it occurs +(see Chapter~\ref{group}). +Thus the output of \begin{verbatim} +\setbox0=\hbox{---} {\wd0=0pt} a\box0b +\end{verbatim} +is `{\setbox0=\hbox{---}{\wd0=0pt}a\box0b}\kern.5em'. + +The limits that hold on the dimensions with which a +box can be created (see above) do not hold for explicit changes to the +\mdqon +size of a box: the assignment \cs{dp0=}""\n{-2pt} for a +\mdqoff +horizontal box is perfectly admissible. + +%\spoint Moving boxes around +\subsection{Moving boxes around} + +In a horizontal box all constituent elements are lined up +\cstoidx raise\par\cstoidx lower\par +with their reference points at the same height as the +reference point of the box. Any box inside a horizontal +box can be lifted or dropped using the macros +\cs{raise} and~\cs{lower}. +\awp + +Similarly, in a vertical box all constituent elements +are lined up with their reference points underneath one another, +in line with the reference point of the box. +Boxes can now be moved sideways by the macros +\csidx{moveleft} and~\csidx{moveright}. + +Only boxes can be shifted thus; these operations cannot +be applied to, for instance, characters or rules. + + +%\spoint Box dimensions and box placement +\subsection{Box dimensions and box placement} + +\TeX\ places the components of horizontal and +vertical lists by maintaining a reference line and a +current position on that line. For horizontal lists +the reference line is the baseline of the surrounding +\cs{hbox}; for vertical lists it is the vertical line +through the reference point of the surrounding \cs{vbox}. + +In horizontal mode a component is placed as follows. +The current position coincides initially +with the reference point of the surrounding box. After that, +the following actions are carried out. +\begin{enumerate} \item If the component has been shifted by +\cs{raise} or \cs{lower}, shift the current +position correspondingly. +\item If the component is a horizontal box, use +this algorithm recursively for its contents; +if it is a vertical box, go up by the height of this box, +putting a new current position for the enclosed vertical list there, +and place its components using the algorithm for vertical +lists below. +\item Move the current position (on the reference line) +to the right by the width of the component. +\end{enumerate} + +For the list in a vertical box \TeX's current position is +initially at the upper left corner of that box, as explained above, +and the reference line is the vertical line through that point; +it also runs through the reference point of the box. +Enclosed components are then placed as follows. +\begin{enumerate} \item If a component has been shifted using +\cs{moveleft} or \cs{moveright}, shift the current position +accordingly. +\item Put the component with its upper left corner at the +current position. +\item If the component is a vertical box, use this algorithm +recursively for its contents; if it is a horizontal box, +its reference point can be found below the current position +by the height of the box. Put the current position for that +box there, and use the above algorithm for horizontal lists. +\item Go down by the height plus depth of the box +(that is, starting at the upper left corner of the box) +on the reference line, +and continue processing vertically. +\end{enumerate} +Note that the above processes do not describe the construction +of boxes. That would (for instance) +involve for vertical boxes the insertion +of baselineskip glue. Rather, it describes the way the components +of a finished box are arranged in the output. + +%\spoint Boxes and negative glue +\subsection{Boxes and negative glue} + +Sometimes it is useful to have boxes overlapping instead of +\awp +line up. An easy way to do this is to use negative glue. +In horizontal mode +\begin{verbatim} +{\dimen0=\wd8 \box8 \kern-\dimen0} +\end{verbatim} +places box 8 without moving the current location. + +More versatile are the macros \csidx{llap} and \csidx{rlap}\label{rlap}, +defined as \begin{verbatim} +\def\llap#1{\hbox to 0pt{\hss #1}} +\end{verbatim} +and \begin{verbatim} +\def\rlap#1{\hbox to 0pt{#1\hss}} +\end{verbatim} +that allow material to protrude left or right from the +current location. +The \cs{hss} glue is equivalent to \verb>\hskip 0pt plus 1fil minus 1fil>, +which absorbs any positive or negative width +of the argument of \cs{llap} or \cs{rlap}. + +\begin{example} The sequence \begin{verbatim} +\llap{\hbox to 10pt{a\hfil}} +\end{verbatim} +is effectively the same as +\begin{verbatim} +\hbox{\hskip-10pt \hbox to 10pt{a\hfil}} +\end{verbatim} +which has a total width of~\n{0pt}. +\end{example} + +%\point[over/underfull] Overfull and underfull boxes +\section{Overfull and underfull boxes} +\label{over/underfull} + +If a box has a size specification \TeX\ will +\term box !overfull\par\term box !underfull\par +stretch or shrink glue in the box. For glue with +only finite stretch or shrink components the {\em badness\/} +(see Chapter~\ref{line:break}) of stretching or shrinking +is computed. +In \TeX\ version~3 the badness +\cstoidx badness\par\term \TeX\ version 3\par +of the box most recently +constructed is available for inspection +by the user through the \cs{badness} parameter. Values for +badness range 0--$10\,000$, but if the box is overfull +it is~$1\,000\,000$. + +When \TeX\ considers the badness too large, +it gives a diagnostic message. Let us first consider error reporting +for horizontal boxes. + +Horizontal boxes of which the glue has to stretch are never reported if +\cstoidx hbadness\par\cstoidx vbadness\par +\cs{hbadness}${}\geq10\,000$; otherwise \TeX\ reports them +as `underfull' if their badness is more than \cs{hbadness}. + +Glue shrinking can lead to `overfull' boxes: a box is called +\cstoidx hfuzz\par\cstoidx vfuzz\par +overfull if the available shrink is less than the shrink +necessary to meet the box specification. An overfull box +is only reported if the difference in shrink is more than +\cs{hfuzz}, or if \cs{hbadness}${}<100$ (and it turns out that +using all available shrinkability has badness~$100$). + +\begin{example} Setting \verb>\hfuzz=1pt> will let \TeX\ ignore +boxes that can not shrink enough if they lack less than~\n{1pt}. +In \begin{verbatim} +\hbox to 1pt{\hskip3pt minus .5pt} +\end{verbatim} +\awp +\begin{verbatim} +\hbox to 1pt{\hskip3pt minus 1.5pt} +\end{verbatim} +only the first box will give an error message: +it is \n{1.5pt} too big, whereas the second lacks +\n{.5pt} which is less than \cs{hfuzz}. +\end{example} + +Also, boxes that shrink but that are not overfull can be reported: +if a box is `tight', that is, if it uses at least half its +shrinkability, \TeX\ reports this fact if the +computed badness (which is between 13 and~100) is more than +\cs{hbadness}. + +For horizontal and vertical boxes this error reporting is almost +\cstoidx overfullrule\par +the same, with parameters \cs{vbadness} and \cs{vfuzz}. +The difference is that for horizontal overfull boxes +\TeX\ will draw a rule to the right of the box that has the +same height as the box, and width \cs{overfullrule}. +No overfull rule ensues if +the \cs{tabskip} glue in an \cs{halign} cannot be +shrunk enough. + + +%\point Opening and closing boxes +\section{Opening and closing boxes} + +The opening and closing braces of a box can be either explicit, +that is, character tokens of category 1 and~2, or implicit, +a control sequence \verb=\let= to such a character. +After the opening brace +the \csidx{everyhbox} or \csidx{everyvbox} +tokens are inserted. +If this box appeared in a \csidx{setbox} assignment +any \csidx{afterassignment} +token is inserted even before the `everybox' tokens. + +\begin{example} \label{every:box:assign}\begin{verbatim} +\everyhbox{b} +\afterassignment a +\setbox0=\hbox{c} +\showbox0 +\end{verbatim} +gives +\begin{verbatim} +> \box0= +\hbox(6.94444+0.0)x15.27782 +.\tenrm a +.\tenrm b +.\kern0.27779 +.\tenrm c +\end{verbatim} +\end{example} + +Implicit braces can be used to let a box be opened or closed +by a macro, for example: +\begin{verbatim} +\def\openbox#1{\setbox#1=\hbox\bgroup} +\def\closebox#1{\egroup\DoSomethingWithBox#1} +\openbox0 ... \closebox0 +\end{verbatim} +This mechanism can be used to scoop up paragraphs: +\begin{verbatim} +\everypar{\setbox\parbox= + \vbox\bgroup + \everypar{} + \def\par{\egroup\UseBox\parbox}} +\end{verbatim} +Here the \cs{everypar} opens the box and lets the text be +set in the box: starting for instance +\begin{verbatim} +Begin a text ... +\end{verbatim} +gives the equivalent of +\begin{verbatim} +\setbox\parbox=\vbox{Begin a text ... +\end{verbatim} +Inside the box \cs{par} has been redefined, so +\begin{verbatim} +... a text ends.\par +\end{verbatim} +is equivalent to +\begin{verbatim} +... a text ends.}\Usebox\parbox +\end{verbatim} + +In this example, the \cs{UseBox} command can only treat the +box as a whole; if the elements of the box should somehow +be treated separately another approach is necessary. +In +\begin{verbatim} +\everypar{\setbox\parbox= + \vbox\bgroup\everypar{}% + \def\par{\endgraf\HandleLines + \egroup\box\parbox}} +\def\HandleLines{ ... \lastbox ... } +\end{verbatim} +the macro \cs{HandleLines} can have access to successive +elements from the vertical list of the paragraph. +See also the example on page~\pageref{varioset}. + +%\point Unboxing +\section{Unboxing} + +Boxes can be unwrapped by the commands \csidx{unhbox} and +\term box! unboxing\par +\csidx{unvbox}, and by their copying versions +\csidx{unhcopy} and \csidx{unvcopy}. +These are horizontal and vertical commands +(see Chapter~\ref{hvmode}), considering that in effect +they contribute a partial horizontal or vertical list. +It is not possible to \cs{unhbox} a register +containing a \cs{vbox} or vice versa, +but a void box register can both be \cs{unhbox}ed and +\cs{unvbox}ed. + +Unboxing takes the contents of a box in a box register and appends +them to the surrounding list; any glue can then +be set anew. Thus +\begin{verbatim} +\setbox0=\hbox to 1cm{\hfil} \hbox to 2cm{\unhbox0} +\end{verbatim} +is completely equivalent to +\begin{verbatim} +\hbox to 2cm{\hfil} +\end{verbatim} +and not to +\begin{verbatim} +\hbox to 2cm{\kern1cm} +\end{verbatim} +\awp + +The intrinsically horizontal nature of \cs{unhbox} is +\cstoidx leavevmode\par +used to define +\begin{verbatim} +\def\leavevmode{\unhbox\voidb@x} +\end{verbatim} +This command switches from vertical mode to horizontal without +adding anything to the horizontal list. +However, the subsequent \cs{indent} caused by this transition +adds an indentation box. +In horizontal mode the \cs{leavevmode} command has no effect. +Note that here it is not necessary to use \cs{unhcopy}, +because the register is empty anyhow. + +Beware of the following subtlety: unboxing in vertical +mode does not add interline glue between the box contents and +any preceding item. +Also, the value of \cs{prevdepth} is not +changed, so glue between the box contents and any following +item will occur only if there was something preceding the box; +interline glue will be based on the depth of that preceding item. +Similarly, unboxing in horizontal mode does not influence +the \cs{spacefactor}. + +%\point Text in boxes +\section{Text in boxes} + +Both horizontal and vertical boxes can contain text. However, +\term boxes !text in\par +the way text is treated differs. +In horizontal boxes +the text is placed in one straight line, and the width of +the box is in principle the natural width of the text +(and other items) contained in it. No \gram{vertical command}s +are allowed inside a horizontal box, and \cs{par} does +nothing in this case. + +For vertical boxes the situation is radically different. +As soon as a character, or any other \gram{horizontal command} +(see page~\pageref{h:com:list}), +is encountered in a vertical box, \TeX\ starts building a paragraph +in unrestricted horizontal mode, that is, just as if the paragraph +were directly part of the page. +At the occurrence of a \gram{vertical command} +(see page~\pageref{v:com:list}), or at the end +of the box, the paragraph is broken into lines using the +current values of parameters such as~\cs{hsize}. + +Thus \begin{verbatim} +\hbox to 3cm{\vbox{some reasonably long text}} +\end{verbatim} +will {\sl not\/} give a paragraph of width 3 centimetres +(it gives an overfull horizontal box if \cs{hsize}${}>{}$\n{3cm}). +However, +\begin{verbatim} +\vbox{\hsize=3cm some reasonably long text} +\end{verbatim} +will be 3 centimetres wide. + +A paragraph of text inside a vertical box is broken into +lines, which are packed in horizontal boxes. +These boxes are then stacked +in internal vertical mode, possibly with +\cs{baselineskip} and \cs{lineskip} separating them +(this is treated in Chapter~\ref{baseline}). +This process is also used for text on the page; the boxes +are then stacked in outer vertical mode. + +If the internal vertical list is empty, no \cs{parskip} +glue is added at the start of a paragraph. + +Because text in a horizontal box is not +\label{wide:vbox}% +broken into lines, there is a further +difference between text in restricted and unrestricted +\awp +horizontal mode. In restricted horizontal mode no +discretionary nodes and whatsit items changing the +value of the current language are inserted. +This may give problems if the text is subsequently +unboxed to form part of a paragraph. + +See Chapter~\ref{line:break} for an explanation of these +items, and \cite{Downs} for a way around this problem. + +%\point Assorted remarks +\section{Assorted remarks} + +%\spoint Forgetting the \cs{box} +\subsection{Forgetting the \cs{box}} + +After \verb.\newcount\foo., one can use \cs{foo} on its own +to get the \cs{foo} counter. +For boxes, however, one has to use \verb.\box\foo. to get +the \cs{foo} box. +The reason for this is that there exists +no separate \cs{boxdef} command, so \cs{chardef} is +used (see Chapter~\ref{alloc}). + +\begin{example} +Suppose \verb.\newbox\foo. allocates box register~25; then +typing \cs{foo} is equivalent to typing +\verb.\char25.. +\end{example} + +%\spoint Special-purpose boxes +\subsection{Special-purpose boxes} + +Some box registers +have a special +purpose: +\begin{itemize} +\item \cs{box255} is by used \TeX\ internally + to give the page to the output routine. +\item \cs{voidb@x} is the number of + a box register allocated in + \n{plain.tex}; it is supposed to be empty always. + It is used in the macro \cs{leavevmode} and others. +\item when a new \cs{insert} is created with the plain \TeX\ + \cs{newinsert} macro, a \cs{count}, + \cs{dimen}, \cs{skip}, and \cs{box} all with the same number + are reserved for that insert. + The numbers for these registers count down from~254. +\end{itemize} + + +%\spoint The height of a vertical box in horizontal mode +\subsection{The height of a vertical box in horizontal mode} + +In horizontal mode a vertical box is placed with its +reference point aligned vertically with the reference +point of the surrounding box. +\TeX\ then traverses its contents starting at the left +upper corner; that is, the point that lies above the reference +point by a distance of the height of the box. +Changing the height of the box implies then that the +contents of the box are placed at a different height. + +Consider as an example +\begin{verbatim} +\hbox{a\setbox0=\vbox{\hbox{b}}\box0 c} +\end{verbatim} +which gives +\begin{disp}\leavevmode\hbox{a\setbox0=\vbox{\hbox{b}}\box0 c}\end{disp} +and +\begin{verbatim} +\hbox{a\setbox0=\vbox{\hbox{b}}\ht0=0cm \box0 c} +\end{verbatim} +\awp +which gives +\begin{disp}\leavevmode\hbox{a\setbox0=\vbox{\hbox{b}}\ht0=0cm \box0 c}\end{disp} + +By contrast, changing the width of a box placed in vertical +mode has no effect on its placement. + +%\spoint More subtleties with vertical boxes +\subsection{More subtleties with vertical boxes} + +Since there are two kinds of vertical boxes, the \cs{vbox} and +the \cs{vtop}, using these two kinds nested may lead to +confusing results. For instance, \begin{verbatim} +\vtop{\vbox{...}} +\end{verbatim} +is completely equivalent to just \begin{verbatim} +\vbox{...} +\end{verbatim} + +It was stated above that +the depth of a \cs{vbox} is zero if the last item +is a kern or glue, and the height of a \cs{vtop} is +zero unless the first item in it is a box. +The above examples used a kern for that first or last item, +but if, in the case of a \cs{vtop}, +this item is not a glue or kern, one is apt to +overlook the effect that it has on the surrounding box. +For instance, +\begin{verbatim} +\vtop{\write16{...}...} +\end{verbatim} +has zero height, +because the write instruction +is packed into a `whatsit' item that is placed on the current, +that is, the vertical, list. +The remedy here is +\begin{verbatim} +\vtop{\leavevmode\write16{...}...} +\end{verbatim} +which puts the whatsit in the beginning of the paragraph, +instead of above it. + +Placement of items in a vertical list is sometimes +a bit tricky. There is for instance a difference between +how vertical and horizontal boxes are treated in a +vertical list. Consider the following examples. +After \cs{offinterlineskip} the first example\begin{verbatim} +\vbox{\hbox{a} + \setbox0=\vbox{\hbox{(}} + \ht0=0pt \dp0=0pt \box0 + \hbox{ b}} +\end{verbatim} +gives \begin{disp}\offinterlineskip\leavevmode\vbox{\hbox{a} + \setbox0=\vbox{\hbox{(}} + \ht0=0pt \dp0=0pt \box0 + \hbox{ b}} +\end{disp} +while a slight variant\begin{verbatim} +\vbox{\hbox{a} + \setbox0=\hbox{(} + \ht0=0pt \dp0=0pt \box0 + \hbox{ b}} +\end{verbatim} +\awp +gives +\begin{disp}\offinterlineskip\leavevmode\vbox{\hbox{a} + \setbox0=\hbox{(} + \ht0=0pt \dp0=0pt + \box0 + \hbox{ b}} +\end{disp} +The difference is caused by the fact that horizontal boxes +are placed with respect to their reference point, but vertical +boxes with respect to their upper left corner. + +%\spoint Hanging the \cs{lastbox} back in the list +\subsection{Hanging the \cs{lastbox} back in the list} + +You can pick the last box off a vertical list that has been +compiled in (internal) vertical mode. +However, if you try to hang it back in the list the vertical +spacing may go haywire. If you just hang it back, +\begin{verbatim} +\setbox\tmpbox=\lastbox +\usethetmpbox \box\tmpbox +\end{verbatim} +baselineskip glue is added a second time. If you `unskip' prior +to hanging the box back, +\begin{verbatim} +\setbox\tmpbox=\lastbox \unskip +\usethetmpbox \box\tmpbox +\end{verbatim} +things go wrong in a more subtle way. +The \gram{internal dimen} \cs{prevdepth} +(which controls interline glue; see Chapter~\ref{baseline}) +will have a +value based on the last box, but what you need for the proper +interline glue is a depth based on one box earlier. +The solution is not to unskip, +but to specify \cs{nointerlineskip}: +\begin{verbatim} +\setbox\tmpbox=\lastbox +\usethetmpbox \nointerlineskip \box\tmpbox +\end{verbatim} + + +%\spoint[varioset] Dissecting paragraphs with \cs{lastbox} +\subsection{Dissecting paragraphs with \cs{lastbox}} +\label{varioset} + +Repeatedly applying \cs{last...} and \cs{un...} macros +\howto Take a paragraph apart\par +can be used to take a paragraph apart. +Here is an example of that. + +\indent\vbox{\message{Check vario look!} +\hyphenpenalty10000 \exhyphenpenalty10000 %\Indent:no +\advance\hsize by -2\parindent +\newif\ifsnap \spaceskip=\fontdimen2\font plus \fontdimen3\font +\def\eatlines{ + \setbox2\lastbox % check the last line + \ifvoid2\global\snaptrue + \else % if it's not empty + \unskip\unpenalty % take whatever is + {\eatlines} % above it; + \setbox4\hbox{\unhcopy2} % collapse this line + \ifdim\wd4<.98\wd2 % if the difference is too large, + \ifsnap \box2 \global\snapfalse + \else \box4 \global\snaptrue + \fi + \else \box2 \global\snapfalse + \fi + \fi} +In typesetting advertisement copy, a way of justifying +paragraphs has become popular in recent years +that is somewhere between flushright and raggedright +setting. +Lines that would stretch beyond certain limits +are set with their glue at natural width. This paragraph +exemplifies this procedure; the macros +follow next.\par\eatlines}\par + +\begin{verbatim} +\newbox\linebox \newbox\snapbox +\def\eatlines{ + \setbox\linebox\lastbox % check the last line + \ifvoid\linebox + \else % if it's not empty + \unskip\unpenalty % take whatever is + {\eatlines} % above it; + % collapse the line + \setbox\snapbox\hbox{\unhcopy\linebox} + % depending on the difference + \ifdim\wd\snapbox<.98\wd\linebox + \box\snapbox % take the one or the other, + \else \box\linebox \fi + \fi} +\end{verbatim} +This macro can be called as +\begin{verbatim} +\vbox{ ... some text ... \par\eatlines} +\end{verbatim} +or it can be inserted automatically +with \cs{everypar}; see~\cite{E1}. + +In the macro \cs{eatlines}, the \cs{lastbox} is taken +from a vertical list. If the list is empty +the last box will test true on \cs{ifvoid}. +These boxes containing lines from a paragraph +are actually horizontal boxes: the test +\cs{ifhbox} applied to them would give a true +result. + +%%%% end of input file [boxes] + +%\InputFile:modes +%%%% this is input file [modes] +%\subject[hvmode] Horizontal and \nl Vertical Mode +\endofchapter +\chapter{Horizontal and Vertical Mode}\label{hvmode} + + +At any point in its processing \TeX\ is in some mode. +\term mode\par +There are six modes, divided in three categories: +\begin{enumerate} \item horizontal mode and restricted horizontal +mode, \item vertical mode and internal vertical mode, and +\item math mode and display math mode.\end{enumerate} +The math modes will be treated elsewhere (see page~\pageref{math:modes}). +Here we shall look +at the horizontal and vertical modes, the kinds of objects +that can occur in the corresponding lists, and the +commands that are exclusive for one mode or the other. + + +\begin{inventory} +\item [\cs{ifhmode}] + Test whether the current mode is (possibly restricted) horizontal mode. + +\item [\cs{ifvmode}] + Test whether the current mode is (possibly internal) vertical mode. + +\item [\cs{ifinner}] + Test whether the current mode is an internal mode. + +\item [\cs{vadjust}] + Specify vertical material for the enclosing vertical list + while in horizontal mode. + +\item [\cs{showlists}] + Write to the log file the contents of the partial lists + currently being built in all modes. +\end{inventory} + +%\point Horizontal and vertical mode +\section{Horizontal and vertical mode} + +When not typesetting mathematics, \TeX\ is in horizontal +or vertical mode, building horizontal or vertical lists +respectively. Horizontal mode is typically used to +make lines of text; vertical mode is typically used +to stack the lines of a paragraph on top of each other. +Note that +these modes +are different from the internal states of \TeX's input processor +(see page~\pageref{input:states}). + +%\spoint Horizontal mode +\subsection{Horizontal mode} + +The main activity in horizontal mode is building lines of text. +\term mode !horizontal\par +Text on the page and text in a \cs{vbox} or \cs{vtop} is built in +horizontal mode (this might be called `paragraph mode'); +if the text is in an \cs{hbox} there is only one line +of text, and the corresponding mode is the restricted +\awp +horizontal mode. + +In horizontal mode all material is added to a horizontal list. +If this list is built in unrestricted horizontal mode, it +will later be broken into lines and added to the surrounding vertical list. + +Each element of a horizontal list is one of the following: +\term list !horizontal\par +\begin{itemize} \item a box (a character, ligature, \cs{vrule}, +or a \gr{box}), +\item a discretionary break, +\item a whatsit (see Chapter~\ref{io}), +\item vertical material enclosed in \cs{mark}, +\cs{vadjust}, or \cs{insert}, +\item +\mdqon +glue or leaders, a kern, a penalty, or a math-on/""off item. +\mdqoff +\end{itemize} +The items in the last point are all discardable. +Discardable items are called that, because they disappear in +\term discardable items\par +a break. Breaking of horizontal +lists is treated in Chapter~\ref{line:break}. + +%\spoint Vertical mode +\subsection{Vertical mode} + +Vertical mode can be used to stack items on top of one another. +\term mode !vertical\par +Most of the time, these items are boxes +containing the lines of paragraphs. + +Stacking material can take place inside a +vertical box, but the +items that are stacked can also +appear by themselves on the page. In the latter case +\TeX\ is in vertical mode; in the former case, inside a +vertical box, \TeX\ operates in internal vertical mode. + +In vertical mode all material is added to a vertical list. +If this list is built in external vertical mode, it +will later be broken when pages are formed. + +Each element of a vertical list is one of the following: +\term list !vertical\par +\begin{itemize} \item a box (a horizontal or vertical box or +an \cs{hrule}), +\item a whatsit, +\item a mark, +\item glue or leaders, a kern, or a penalty.\end{itemize} +The items in the last point are all discardable. +Breaking of vertical lists +is treated in Chapter~\ref{page:break}. + +There are a few exceptional conditions at the beginning +of a vertical list: the value of \cs{prevdepth} is set +to \n{-1000pt}. Furthermore, no \cs{parskip} glue is added +at the top of an internal vertical list; +at the top of the main vertical list (the top of the +`current page') no glue or other discardable items +are added, and \cs{topskip} glue is added when the +first box is placed on this list +(see Chapters \ref{page:shape} and~\ref{page:break}). + +%\point Horizontal and vertical commands +\section{Horizontal and vertical commands} + +Some commands are so intrinsically horizontal or vertical +in nature that they force \TeX\ to go into that mode, if +possible. A~command that forces \TeX\ into horizontal mode +is called a \gr{horizontal command}; similarly a command that +forces \TeX\ into vertical mode is called a +\awp +\gr{vertical command}. + +However, not all transitions are possible: +\TeX\ can switch from both vertical modes to +(unrestricted) horizontal mode and back +through horizontal and vertical commands, but no transitions +to or from restricted horizontal mode are possible +(other than by enclosing horizontal boxes in vertical boxes or +the other way around). +A~vertical command in restricted horizontal mode thus gives +an error; the \cs{par} command in restricted horizontal mode +has no effect. + +The horizontal commands are the following: +\label{h:com:list}\term horizontal commands\par +\begin{itemize} +\item any \gr{letter}, \gr{otherchar}, \cs{char}, +a control sequence defined by \cs{chardef}, or \cs{noboundary}; +\item \cs{accent}, \cs{discretionary}, the discretionary +hyphen~\verb|\-| and control space~\verb|\|\n{\char32}; +\item \cs{unhbox} and \cs{unhcopy}; +\item \cs{vrule} and the +\gr{horizontal skip} commands +\cs{hskip}, \cs{hfil}, \cs{hfill}, \cs{hss}, and \cs{hfilneg}; +\item \cs{valign}; +\item math shift (\n\$). +\end{itemize} + +The vertical commands are the following: +\label{v:com:list}\term vertical! commands\par +\begin{itemize} +\item \cs{unvbox} and \cs{unvcopy}; +\item \cs{hrule} and the \gr{vertical skip} commands + \cs{vskip}, \cs{vfil}, \cs{vfill}, \cs{vss}, and \cs{vfilneg}; +\item \cs{halign}; +\item \cs{end} and \cs{dump}. +\end{itemize} +Note that the vertical commands do not include \cs{par}; +nor are \cs{indent} and \cs{noindent} horizontal commands. + +The connection between boxes and modes is explored below; +see Chapter~\ref{rules} for more on the connection between +rules and modes. + +%\point The internal modes +\section{The internal modes} + +Restricted horizontal mode and internal vertical mode +\term mode !restricted\par\term mode !internal\par +are the variants of horizontal mode and vertical mode +that hold inside an \cs{hbox} and \cs{vbox} (or \cs{vtop} +or \cs{vcenter}) respectively. +However, restricted horizontal mode is rather more +restricted in nature than internal vertical mode. +The third internal mode is non-display math mode +(see Chapter~\ref{math}). + +%\spoint Restricted horizontal mode +\subsection{Restricted horizontal mode} + +The main difference between restricted horizontal mode, +the mode in an \cs{hbox}, and unrestricted horizontal mode, +the mode in which paragraphs in vertical boxes +and on the page are built, +is that you cannot break out of restricted horizontal mode: +\cs{par}~does nothing in this mode. +Furthermore, a~\gram{vertical command} in restricted horizontal +mode gives an error. +In unrestricted horizontal mode it would cause a +\cs{par} token to be inserted and vertical mode to be entered +(see also Chapter~\ref{par:end}). +\awp + +%\spoint Internal vertical mode +\subsection{Internal vertical mode} + +Internal vertical mode, the vertical mode inside +a~\cs{vbox}, is a lot like external vertical +mode, the mode in which pages are built. +A~\gram{horizontal command} in internal vertical mode, +for instance, is perfectly valid: +\TeX\ then starts building a paragraph in +unrestricted horizontal mode. + +One difference is that the commands +\cs{unskip} and \cs{unkern} have no effect +in external vertical mode, and +\cs{lastbox} is always empty in external vertical mode. +See further pages \pageref{lastbox} and~\pageref{unskip}. + +The entries of alignments (see Chapter~\ref{align}) are +processed in internal modes: restricted horizontal mode +for the entries of an \cs{halign}, and internal vertical +mode for the entries of a~\cs{valign}. +The material in \cs{vadjust} and \cs{insert} items +is also processed in internal vertical mode; furthermore, +\TeX\ enters this mode when processing the \cs{output} token list. + +The commands \cs{end} and \cs{dump} (the latter exists only in \IniTeX) +are not allowed in +internal vertical mode; furthermore, \cs{dump} is not allowed +inside a group (see Chapter~\ref{TeXcomm}). + + +%\point[hvbox] Boxes and modes +\section{Boxes and modes} +\label{hvbox} + +There are horizontal and vertical boxes, and there is +horizontal and vertical mode. Not surprisingly, there is +a connection between the boxes and the modes. +One can ask about this connection in two ways. + +%\spoint What box do you use in what mode? +\subsection{What box do you use in what mode?} + +This is the wrong question. Both horizontal and vertical boxes +can be used in both horizontal and vertical mode. +Their placement is determined by the prevailing mode at that moment. + +%\spoint What mode holds in what box? +\subsection{What mode holds in what box?} + +This is the right question. +When an \cs{hbox} starts, \TeX\ is in restricted horizontal +mode. Thus everything in a horizontal box is lined up horizontally. + +When a \cs{vbox} is started, \TeX\ is in internal vertical mode. +Boxes of both kinds and other items are then stacked +on top of each other. + + +%\spoint Mode-dependent behaviour of boxes +\subsection{Mode-dependent behaviour of boxes} + +Any \gr{box} (see Chapter \ref{boxes} for the full definition) +can be used in horizontal, vertical, and math mode. +Unboxing commands, however, are specific for horizontal or vertical mode. +Both \cs{unhbox} and \cs{unhcopy} are \gr{horizontal command}s, +so they can make \TeX\ switch from vertical to horizontal +mode; +\awp +both \cs{unvbox} and \cs{unvcopy} are \gr{vertical command}s, +so they can make \TeX\ switch from horizontal to vertical +mode. + +In horizontal mode the \cs{spacefactor} is set to 1000 +after a box has been placed. In vertical mode the +\cs{prevdepth} is set to the depth of the box placed. +Neither statement holds for +unboxing commands: after an \cs{unhbox} or \cs{unhcopy} the +spacefactor is not altered, and after \cs{unvbox} or \cs{unvcopy} +the \cs{prevdepth} remains unchanged. +After all, these commands do not add a box, +but a piece of a~(horizontal or vertical) list. + +The operations \cs{raise} and \cs{lower} can only be +applied to a box in horizontal mode; similarly, \cs{moveleft} and +\cs{moveright} can only be applied in vertical mode. + + +%\point Modes and glue +\section{Modes and glue} + +Both in horizontal and vertical mode +\TeX\ can insert glue items the size of which is +determined by the preceding object in the list. + +For horizontal mode the amount of glue that is inserted +for a space token depends on the \cs{spacefactor} of +the previous object in the list. This is treated +in Chapter~\ref{space}. + +In vertical mode \TeX\ inserts glue to keep boxes at a certain +distance from each other. This glue is influenced by the +height of the current item and the depth of the previous one. +The depth of items is recorded in the \cs{prevdepth} parameter +(see Chapter~\ref{baseline}). + +The two quantities \cs{prevdepth} +and \cs{spacefactor} +use the same internal register of \TeX. Thus the \cs{prevdepth} +can be used or asked only in vertical mode, and the \cs{spacefactor} +only in horizontal mode. + +%\point[migrate] Migrating material +\section{Migrating material} +\label{migrate} + +The three control sequences \cs{insert}, \cs{mark}, and \cs{vadjust} +can be given in a paragraph +\term migrating material\par +(the first two can also occur +in vertical mode) to specify material that will wind up on the +surrounding vertical list. Note that this need not be +the main vertical list: it can be a vertical box +containing a paragraph of text. In this case a \cs{mark} +or \cs{insert} command will not reach the page breaking algorithm. + +When several migrating items are specified in a certain line +of text, their left-to-right order is preserved when they are +placed on the surrounding vertical list. These items are placed +directly after the horizontal box containing the line of text +in which they were specified: they come before any +penalty or glue items that are automatically inserted +(see page~\pageref{between:lines}). + +%\spoint \cs{vadjust} +\subsection{\cs{vadjust}} + +The command +\cstoidx vadjust\par +\begin{disp}\cs{vadjust}\gr{filler}\lb\gr{vertical mode material}\rb\end{disp} +\awp +is only allowed in horizontal and math modes (but it is +not a \gr{horizontal command}). +Vertical mode material specified by \cs{vadjust} is moved from +the horizontal list in which the command is given +to the surrounding vertical list, directly after the box +in which it occurred. + +In the current line +\vadjust{\setbox0=\hbox{$\bullet$\hskip1em}\ht0=0pt \dp0=0pt \llap{\box0}} +a \cs{vadjust} item was placed to put the bullet in the margin. + + +Any vertical material in a \cs{vadjust} item is processed +in internal vertical mode, even though it will wind up +on the main vertical list. For instance, the \cs{ifinner} +test is true in a \cs{vadjust}, and at the start +\mdqon +of the vertical material \cs{prevdepth}$=$""\n{-1000pt}. +\mdqoff + +%\point Testing modes +\section{Testing modes} + +The three conditionals \cs{ifhmode}, \cs{ifvmode}, and +\cs{ifinner} can distinguish between the four modes of +\TeX\ that are not math modes. +The \cs{ifinner} test is true if \TeX\ is in +restricted horizontal mode or internal vertical mode +(or in non-display math mode). +Exceptional condition: during a \cs{write} \TeX\ +is in a `no mode' state. The tests \cs{ifhmode}, +\cs{ifvmode}, and \cs{ifmmode} are then all false. + +Inspection of all current lists, including the `recent +contributions' (see Chapter~\ref{page:break}), +is possible through the command \csidx{showlists}\label{showlists}. +This command writes to the log file the contents of all +lists that are being built at the moment the command is given. + +Consider the example \begin{verbatim} +a\hfil\break b\par +c\hfill\break d +\hbox{e\vbox{f\showlists +\end{verbatim} +Here the first paragraph has been broken into two lines, and +these have been added to the current page. The second paragraph +has not been concluded or broken into lines. + +The log file shows the following. \TeX\ was busy +building a paragraph (starting with an indentation box +\n{20pt} wide):\begin{verbatim} +### horizontal mode entered at line 3 +\hbox(0.0+0.0)x20.0 +\tenrm f +spacefactor 1000 +\end{verbatim} +This paragraph was inside a vertical box:\begin{verbatim} +### internal vertical mode entered at line 3 +prevdepth ignored +\end{verbatim} +The vertical box was in a horizontal box, +\begin{verbatim} +### restricted horizontal mode entered at line 3 +\tenrm e +spacefactor 1000 +\end{verbatim} +\awp +which was part of +an as-yet unfinished paragraph:\begin{verbatim} +### horizontal mode entered at line 2 +\hbox(0.0+0.0)x20.0 +\tenrm c +\glue 0.0 plus 1.0fill +\penalty -10000 +\tenrm d +etc. +spacefactor 1000 +\end{verbatim} +Note how the infinite glue and the \cs{break} penalty +are still part of the horizontal list. + +Finally, the first paragraph has been broken into lines and +added to the current page:\begin{verbatim} +### vertical mode entered at line 0 +### current page: +\glue(\topskip) 5.69446 +\hbox(4.30554+0.0)x469.75499, glue set 444.75497fil +.\hbox(0.0+0.0)x20.0 +.\tenrm a +.\glue 0.0 plus 1.0fil +.\penalty -10000 +.\glue(\rightskip) 0.0 +\penalty 300 +\glue(\baselineskip) 5.05556 +\hbox(6.94444+0.0)x469.75499, glue set 464.19943fil +.\tenrm b +.\penalty 10000 +.\glue(\parfillskip) 0.0 plus 1.0fil +.\glue(\rightskip) 0.0 +etc. +total height 22.0 plus 1.0 + goal height 643.20255 +prevdepth 0.0 +\end{verbatim} + + + +%%%% end of input file [modes] + +%\InputFile:number +%%%% this is input file [number] +%\subject[number] Numbers +\endofchapter +\chapter{Numbers}\label{number} + +In this chapter integers and their +denotations will be treated, +the conversions that are possible either way, +allocation and use of \cs{count} registers, and +arithmetic with integers. + +\begin{inventory} +\item [\cs{number}] + Convert a \gr{number} to decimal representation. + +\item [\cs{romannumeral}] + Convert a positive \gr{number} to lowercase roman representation. + +\item [\cs{ifnum}] + Test relations between numbers. + +\item [\cs{ifodd}] + Test whether a number is odd. + +\item [\cs{ifcase}] + Enumerated case statement. + + +\item [\cs{count}] + Prefix for count registers. + +\item [\cs{countdef}] + Define a control sequence to be a synonym for + a~\cs{count} register. + +\item [\cs{newcount}] + Allocate an unused \cs{count} register. + +\item [\cs{advance}] + Arithmetic command to add to or subtract from + a~\gr{numeric variable}. + +\item [\cs{multiply}] + Arithmetic command to multiply a \gr{numeric variable}. + +\item [\cs{divide}] + Arithmetic command to divide a \gr{numeric variable}. + +\end{inventory} + + +%\point Numbers and \gr{number}s +\section{Numbers and \gr{number}s} + +An important part of the grammar of \TeX\ +\term numbers\par\term integers\par +is the rigorous definition of a \gr{number}, the syntactic +entity that \TeX\ expects when semantically an integer is +expected. This definition will take the largest part of this +chapter. Towards the end, \cs{count} registers, arithmetic, +and tests for numbers are treated. + +For clarity of discussion a distinction will be made +here between integers and numbers, +but note that a \gr{number} can be both +an `integer' and a `number'. +`Integer' will be taken to denote a mathematical number: +a~quantity that can be added or multiplied. +`Number' will be taken to refer to the printed representation +of an integer: a string of digits, in other words. + +%\point Integers +\section{Integers} + +Quite a few different sorts of objects can function +as integers in \TeX. In this section they will all +be treated, accompanied by the relevant lines from +the grammar of \TeX. +\awp + +First of all, an integer can be positive or negative: +\begin{disp}\gr{number} $\longrightarrow$ +\gr{optional signs}\gr{unsigned number}\nl +\gr{optional signs} $\longrightarrow$ \gr{optional spaces}\nl +\indent $|$ \gr{optional signs}\gr{plus or minus}\gr{optional spaces} +\end{disp} + +A first possibility for an unsigned integer is a string of digits +in decimal, octal, or hexadecimal notation. +Together with the alphabetic constants these will be named +here \gr{integer denotation}. +Another possibility for an integer is an +internal integer quantity, an \gr{internal integer}; +together with the denotations these form the +\gr{normal integer}s. +Lastly an integer can be a \gr{coerced integer}: +an internal \gr{dimen} or \gr{glue} +quantity that is converted to an integer value. +\begin{disp}\gr{unsigned number} $\longrightarrow$ \gr{normal integer} +$|$ \gr{coerced integer}\nl +\gr{normal integer} $\longrightarrow$ \gr{integer denotation} +$|$ \gr{internal integer}\nl +\gr{coerced integer} $\longrightarrow$ \gr{internal dimen} +$|$ \gr{internal glue}\end{disp} +All of these possibilities will be treated in sequence. + + +%\spoint[int:denotation] Denotations: integers +\subsection{Denotations: integers} +\label{int:denotation} + +Anything that looks like a number +can be used as a \gr{number}: thus \verb-42- is a number. +However, bases other than decimal can also be used: +\begin{verbatim} +'123 +\end{verbatim} +is the octal notation for $1\times8^2+2\times8^1+3\times8^0=83$, +and \begin{verbatim} +"123 +\end{verbatim} +is the hexadecimal notation +for $1\times16^2+2\times16^1+3\times16^0=291$. +\begin{disp}\gr{integer denotation} $\longrightarrow$ +\gr{integer constant}\gr{one optional space} \nl +\indent $|$ \n{\char`\'}\gr{octal constant}\gr{one optional space}\nl +\indent $|$ \n{\char`\"}\gr{hexadecimal constant}\gr{one optional space} +\end{disp} +The octal digits are \n0--\n7; a~digit \n8 or~\n9 following an +octal denotation is not part of the number: +after \begin{verbatim} +\count0='078 +\end{verbatim} +the \cs{count0} will have the value~7, and the +digit~\n8 is typeset. + +The hexadecimal digits are \n0--\n9, \n A--\n F, +where the \n A--\n F can +have category code 11 or~12. The latter has a somewhat +far-fetched justification: the characters resulting from a +\cs{string} operation have category code~12. +Lowercase \n a--\n f are not +hexadecimal digits, although (in \TeX3) they are used +for hexadecimal notation in +the `circumflex method' for accessing all character codes +(see Chapter~\ref{char}). + +%\spoint Denotations: characters +\subsection{Denotations: characters} + +A character token is a pair consisting of a character code, +which is a~number in the range 0--255, +and a category code. Both of these codes are accessible, +and can be used as a \gr{number}. +\awp + +The character code of a character token, or of a single letter +control sequence, is accessible through the left quote command: +both \verb-`a- and~\verb-`\a- denote the character code of~{\tt a}, +which can be used as an integer. +\begin{disp}\gr{integer denotation} $\longrightarrow$ +\n{\char`\`}\gr{character token}\gr{one optional space}\end{disp} + +In order to emphasize that accessing the character code is +in a sense using a denotation, the syntax of \TeX\ allows +an optional space after such a `character constant'. +The left quote must have category~12. + +%\spoint Internal integers +\subsection{Internal integers} + +The class of \gr{internal integers} can +be split into five parts. +The \gr{codename}s and \gr{special integer}s +will be treated separately below; furthermore, there are the following. + +\begin{itemize} \item The contents of \cs{count} registers; +either explicitly used by writing for instance \cs{count23}, +or by referring to such a register by means of a +control sequence +that was defined by \cs{countdef}: +after \begin{verbatim} +\countdef\MyCount=23 +\end{verbatim} +\cs{MyCount} is called a +\gr{countdef token}, and it is fully equivalent to \cs{count23}. + +\item All parameters of \TeX\ that hold integer values; +this includes obvious ones such as \cs{linepenalty}, but +also parameters such as +\cs{hyphenchar}\gr{font} and \cs{parshape} +(if a paragraph shape has been defined for $n$ lines, +using \cs{parshape} in the context of a \gr{number} +will yield this value of~$n$). + +\item\label{num:chardef} Tokens defined by \cs{chardef} or \cs{mathchardef}. +After \begin{verbatim} +\chardef\foo=74 +\end{verbatim} +the control sequence \cs{foo} +can be used on its own to mean \cs{char74}, but in a context +where a \gr{number} is wanted it can be used to denote~74: +\begin{verbatim} +\count\foo +\end{verbatim} +is equivalent to \verb=\count74=. +This fact is +exploited in the allocation routines for registers (see +Chapter~\ref{alloc}). + +A control sequence thus defined by \cs{chardef} is called a +\gr{chardef token}; if it is defined by \cs{mathchardef} it +is called a \gr{mathchardef token}. + +\end{itemize} + +Here is the full list: +\begin{disp}\gr{internal integer} $\longrightarrow$ +\gr{integer parameter} \nl +\indent $|$ \gr{special integer} $|$ \cs{lastpenalty}\nl +\indent $|$ \gr{countdef token} $|$ \cs{count}\gr{8-bit number}\nl +\indent $|$ \gr{chardef token} $|$ \gr{mathchardef token}\nl +\indent $|$ \gr{codename}\gr{8-bit number}\nl +\indent $|$ \cs{hyphenchar}\gr{font} $|$ \cs{skewchar}\gr{font} +$|$ \cs{parshape}\nl +\indent $|$ \cs{inputlineno} $|$ \cs{badness}\nl +\gr{integer parameter} $\longrightarrow$\vadjust{\nobreak} +$|$ \cs{adjdemerits} $|$ \cs{binoppenalty}\nl +\indent $|$ \cs{brokenpenalty} $|$ \cs{clubpenalty} $|$ \cs{day}% +\awp +\nl +\indent $|$ \cs{defaulthyphenchar} $|$ \cs{defaultskewchar} \nl +\indent $|$ \cs{delimiterfactor} $|$ \cs{displaywidowpenalty} \nl +\indent $|$ \cs{doublehyphendemerits} $|$ \cs{endlinechar} + $|$ \cs{escapechar}\nl +\indent $|$ \cs{exhypenpenalty} $|$ \cs{fam} $|$ \cs{finalhyphendemerits}\nl +\indent $|$ \cs{floatingpenalty} $|$ \cs{globaldefs} $|$ \cs{hangafter}\nl +\indent $|$ \cs{hbadness} $|$ \cs{hyphenpenalty} + $|$ \cs{interlinepenalty}\nl +\indent $|$ \cs{linepenalty} $|$ \cs{looseness} $|$ \cs{mag}\nl +\indent $|$ \cs{maxdeadcycles} $|$ \cs{month} \nl +\indent $|$ \cs{newlinechar} $|$ \cs{outputpenalty} $|$ \cs{pausing}\nl +\indent $|$ \cs{postdisplaypenalty} $|$ \cs{predisplaypenalty}\nl +\indent $|$ \cs{pretolerance} $|$ \cs{relpenalty} $|$ \cs{showboxbreadth}\nl +\indent $|$ \cs{showboxdepth} $|$ \cs{time} $|$ \cs{tolerance}\nl +\indent $|$ \cs{tracingcommands} $|$ \cs{tracinglostchars} + $|$ \cs{tracingmacros}\nl +\indent $|$ \cs{tracingonline} $|$ \cs{tracingoutput} + $|$ \cs{tracingpages}\nl +\indent $|$ \cs{tracingparagraphs} $|$ \cs{tracingrestores} + $|$ \cs{tracingstats}\nl +\indent $|$ \cs{uchyph} $|$ \cs{vbadness} $|$ \cs{widowpenalty} + $|$ \cs{year} +\end{disp} + +Any internal integer can function as an \gr{internal unit}, +which \ldash preceded by \gr{optional spaces} \rdash +can serve as a \gr{unit of measure}. +Examples of this are given in Chapter~\ref{glue}. + +%\spoint Internal integers: other codes of a character +\subsection{Internal integers: other codes of a character} + +The \cs{catcode} command +(which was described in Chapter~\ref{mouth}) +is a \gr{codename}, and like the other code names +it can be used as an integer. +\begin{disp}\gr{codename} $\longrightarrow$ \cs{catcode} $|$ \cs{mathcode} +$|$ \cs{uccode} $|$ \cs{lccode}\nl \indent $|$ \cs{sfcode} $|$ \cs{delcode} +\end{disp} +A~\gr{codename} has to be followed by an \gr{8-bit number}. + +Uppercase and lowercase codes were treated in Chapter~\ref{char}; +the \cs{sfcode} is treated +in Chapter~\ref{space}; +the \cs{mathcode} and~\cs{delcode} are treated in +Chapter~\ref{mathchar}. + +%\spoint[special:int:list] \gr{special integer} +\subsection{\gr{special integer}} +\label{special:int:list} + +One of the subclasses of the internal integers is +that of the special integers. +\begin{disp}\gr{special integer} $\longrightarrow$ +\cs{spacefactor} $|$ \cs{prevgraf}\nl +\indent $|$ \cs{deadcycles} $|$ \cs{insertpenalties} +\end{disp} +An assignment to any of these is called an \gr{intimate +assignment}, and is automatically global +(see Chapter~\ref{group}). + +%\spoint Other internal quantities: coersion to integer +\subsection{Other internal quantities: coersion to integer} + +\TeX\ provides a conversion between dimensions and integers: +if an integer is expected, a \gr{dimen} or \gr{glue} used +in that context is converted by taking its +\awp +(natural) size +in scaled points. +However, only \gr{internal dimen}s and \gr{internal glue} +can be used this way: no dimension or glue denotations +can be coerced to integers. + +%\spoint Trailing spaces +\subsection{Trailing spaces} + +The syntax of \TeX\ defines integer denotations (decimal, +octal, and hexadecimal) and `back-quoted' character tokens +to be followed by \gr{one optional space}. This means that +\TeX\ reads the token after the number, absorbing it +if it was a space token, and backing up if it was not. + +Because \TeX's input processor goes into the state `skipping spaces' +after it has seen one space token, this +scanning behaviour implies that +integer denotations can be followed by +arbitrarily many space characters in the input. +Also, a line end is admissible. +However, only one space token is allowed. + +%\point Numbers +\section{Numbers} + +\TeX\ can perform an implicit conversion from a string +\term number! conversion\par\term number!roman numerals\par +\cstoidx number\par\cstoidx romannumeral\par +of digits to an integer. Conversion from a representation +in decimal, octal, or hexadecimal notation was + treated above. The conversion the other way, +from an \gr{internal integer} to a printed representation, +has to be performed explicitly. +\TeX\ provides two conversion routines, +\cs{number} and \cs{romannumeral}. +The command \cs{number} is equivalent to \cs{the} +when followed by an internal integer. +These commands are performed in the expansion processor of \TeX, that is, +they are expanded whenever expansion has not been inhibited. + +Both commands +yield a string of tokens with category code~12; +their argument is a~\gr{number}. +Thus \verb-\romannumeral51-, \verb-\romannumeral\year-, +and~\verb-\number\linepenalty- are valid, and so is~\verb-\number13-. +Applying \cs{number} to a denotation has some uses: +it removes leading zeros and superfluous plus and minus signs. + +A roman numeral is a string of lowercase `roman digits', +which are characters of category code~12. +The sequence\howto Uppercase roman numberals\par +\begin{verbatim} +\uppercase\expandafter{\romannumeral ...} +\end{verbatim} +gives uppercase roman numerals. +This works because \TeX\ expands +tokens in order to find the opening brace of the argument +of \verb=\uppercase=. If \cs{romannumeral} is applied to +a negative number, the result is simply empty. + +%\point Integer registers +\section{Integer registers} + +Integers can be stored in \csidx{count} registers: +\begin{Disp}\cs{count}\gr{8-bit number}\end{Disp} +is an \gr{integer variable} and an \gr{internal integer}. +As an integer variable it can be used in a +\gr{variable assignment}: +\begin{Disp}\gr{variable assignment} $\longrightarrow$ + \gr{integer variable}\gr{equals}\gr{number} $|$ \dots\end{Disp} +\awp +As an internal integer it can be used as a \gr{number}: +\begin{Disp}\gr{number} $\rightarrow$ \gr{optional signs}\gr{internal integer} + $|$ \dots +\end{Disp} + +Synonyms for \cs{count} registers can be introduced by the +\csidx{countdef} command in a \gr{shorthand definition}: +\begin{Disp}\cs{countdef}\gr{control sequence}\gr{equals}\gr{8-bit number} +\end{Disp} A control sequence defined this way +is called a \gr{countdef token}, and it serves as an +\gr{internal integer}. + +The plain \TeX\ macro \csidx{newcount} +(which is declared \cs{outer}) uses the \cs{countdef} command +to allocate an unused \cs{count} register. +Counters 0--9 are scratch registers, like all +registers with numbers~0--9. +However, counters 0--9 are used for page identification +in the \n{dvi} file (see Chapter~\ref{TeXcomm}), +so they should be used as scratch +registers only inside a group. +Counters 10--22 are +used for plain \TeX's bookkeeping of allocation of registers. +Counter 255 is also scratch. + +%\point Arithmetic +\section{Arithmetic} + +The user can perform some arithmetic in \TeX, and +\term arithmetic\par +\TeX\ also performs arithmetic internally. User arithmetic +is concerned only with integers; the internal arithmetic +is mostly on fixed-point quantities, and only in the +case of glue setting on floating-point numbers. + +%\spoint Arithmetic statements +\subsection{Arithmetic statements} + +\TeX\ allows the user to +\cstoidx advance\par\cstoidx multiply\par\cstoidx divide\par +perform some arithmetic on integers. The statement +\begin{Disp}\cs{advance}\gr{integer variable}\gr{optional \n{by}}% + \gr{number}\end{Disp} +adds the value of the \gr{number} + \ldash which may be negative \rdash to the \gr{integer variable}. +Similarly, +\begin{Disp}\cs{multiply}\gr{integer variable}\gr{optional \n{by}}% + \gr{number}\end{Disp} +multiplies the value of the \gr{integer variable}, and +\begin{Disp}\cs{divide}\gr{integer variable}\gr{optional \n{by}}% + \gr{number}\end{Disp} +divides an \gr{integer variable}. + +Multiplication and division are also available for any so-called +\gr{numeric variable}: their most general form is +\begin{disp}\cs{multiply}\gr{numeric variable}\gr{optional \n{by}}\gr{number} +\end{disp} where +\begin{disp}\gr{numeric variable} $\longrightarrow$ +\gr{integer variable} $|$ \gr{dimen variable}\nl +\indent $|$ \gr{glue variable} $|$ \gr{muglue variable}\end{disp} + +The result of an arithmetic operation should not exceed +\awp +$2^{30}$ in absolute value. + +Division of integers yields an integer; that is, the remainder +is discarded. This raises the question of how rounding is performed +when either operand is negative. In such cases \TeX\ performs +the division with the absolute values of the operands, and +takes the negative of the result if exactly one operand was negative. + +%\spoint Floating-point arithmetic +\subsection{Floating-point arithmetic} + +Internally some arithmetic on floating-point quantities +\term arithmetic! floating-point\par +is performed, namely +in the calculation of glue set ratios. +%and slant for accents!! +However, machine-dependent aspects of rounding cannot +influence the decision process of \TeX, so machine independence +of \TeX\ is guaranteed in this respect (sufficient +accuracy of rounding is enforced by the \n{Trip} test of~\cite{K:trip}). + +%\spoint Fixed-point arithmetic +\subsection{Fixed-point arithmetic} + +All fractional arithmetic in \TeX\ is performed in fixed-point +\term arithmetic! fixed-point\par +arithmetic of `scaled integers': multiples of~$2^{-16}$. +This ensures the machine independence of \TeX. +Printed representations of scaled integers are rounded +to 5 decimal digits. + +In ordinary 32-bit implementations of \TeX\ the largest +integers are $2^{31}-1$ in absolute size. +The user is not allowed to specify +dimensions larger in absolute size than~$2^{30}-1$: two +such dimensions can be added or subtracted without +overflow on a 32-bit system. + +%\point Number testing +\section{Number testing} + +The most general test for integers in \TeX\ is +\begin{disp}\cs{ifnum}\gr{number$_1$}\gr{relation}\gr{number$_2$}\end{disp} +where \gr{relation} is a~\n<, \n>, or~\n= character, +all of category~12. + +Distinguishing between odd and even numbers is done +by \begin{disp}\cs{ifodd}\gr{number}\end{disp} + +A numeric case statement is provided by +\begin{disp}\cs{ifcase}\gr{number}\gr{case$_0$}\cs{or}\n{...}\cs{or}% + \gr{case$_n$}\cs{else}\gr{other cases}\cs{fi}\end{disp} +where the \cs{else}-part is optional. The tokens for \gr{case$_i$} +are processed if the number turns out to be~$i$; other cases are +skipped, similarly to what ordinarily happens in conditionals +(see Chapter~\ref{if}). + +%\point Remarks +\section{Remarks} + +%\spoint Character constants +\subsection{Character constants} + +In formats and macro collections numeric constants +are often needed. There are several ways to implement these +in \TeX. +\awp + +Firstly, +\begin{verbatim} +\newcount\SomeConstant \SomeConstant=42 +\end{verbatim} +This is wasteful, as it uses up a \cs{count} register. + +Secondly, +\begin{verbatim} +\def\SomeConstant{42} +\end{verbatim} +Better but accident prone: \TeX\ has to expand to find the number + \ldash which in itself is a slight overhead \rdash and may inadvertently +expand some tokens that should have been left alone. + +Thirdly, +\begin{verbatim} +\chardef\SomeConstant=42 +\end{verbatim} +This one is fine. +A \gr{chardef token} has the same status as a \cs{count} +register: both are \gr{internal integer}s. +Therefore a number defined this way can be used everywhere that +a \cs{count} register is feasible. +For large numbers the \cs{chardef} can be replaced by \cs{mathchardef}, +which runs to \verb>"7FFF>${}=32\,767$. +Note that a \gr{mathchardef token} can usually only appear +in math mode, but in the context of a number it can appear anywhere. + +%\spoint Expanding too far / how far +\subsection{Expanding too far / how far} + +It is a common mistake to write pieces of \TeX\ code +where \TeX\ will inadvertently expand something because it +is trying to compose a number. For example: +\begin{verbatim} +\def\par{\endgraf\penalty200} +...\par \number\pageno +\end{verbatim} +Here the page number will be absorbed into the value of the penalty. + +Now consider +\begin{verbatim} +\newcount\midpenalty \midpenalty=200 +\def\par{\endgraf\penalty\midpenalty} +...\par \number\pageno +\end{verbatim} +Here the page number is not scooped up by mistake: +\TeX\ is trying to locate a \gr{number} after the \cs{penalty}, +and it finds a \gr{countdef token}. This is {\em not\/} +converted to a representation in digits, so there is never any +danger of the page number being touched. + +It is possible to convert a \gr{countdef token} first to +a representation in digits before assigning it: +\begin{verbatim} +\penalty\number\midpenalty +\end{verbatim} +and this brings back again all previous problems of expansion. + + +%%%% end of input file [number] + +%\InputFile:glue +%%%% this is input file [glue] +%\subject[glue] Dimensions and Glue +\endofchapter +\chapter{Dimensions and Glue}\label{glue} + +In \TeX\ vertical and horizontal white space +can have a possibility to adjust itself through `stretching' or +\term glue\par +`shrinking'. An~adjustable white space is called `glue'. +This chapter treats all technical concepts related to +dimensions and glue, and it explains how the badness of stretching or shrinking +a certain amount is calculated. + + +\begin{inventory} +\item [\cs{dimen}] + Dimension register prefix. + +\item [\cs{dimendef}] + Define a control sequence to be a synonym for + a~\cs{dimen} register. + +\item [\cs{newdimen}] + Allocate an unused dimen register. + +\item [\cs{skip}] + Skip register prefix. + +\item [\cs{skipdef}] + Define a control sequence to be a synonym for + a~\cs{skip} register. + +\item [\cs{newskip}] + Allocate an unused skip register. + +\item [\cs{ifdim}] + Compare two dimensions. + +\item [\cs{hskip}] + Insert in horizontal mode a glue item. + +\item [\csidx{hfil}] + Equivalent to + \verb-\hskip 0cm plus 1fil-. + +\item [\csidx{hfilneg}] + Equivalent to + \verb-\hskip 0cm minus 1fil-. + +\item [\csidx{hfill}] + Equivalent to + \verb-\hskip 0cm plus 1fill-. + +\item [\csidx{hss}] + Equivalent to + \verb-\hskip 0cm plus 1fil minus 1fil-. + +\item [\cs{vskip}] + Insert in vertical mode a glue item. + +\item [\csidx{vfil}] + Equivalent to + \verb-\vskip 0cm plus 1fil-. + +\item [\csidx{vfill}] + Equivalent to + \verb-\vskip 0cm plus 1fill-. + +\item [\csidx{vfilneg}] + Equivalent to + \verb-\vskip 0cm minus 1fil-. + +\item [\csidx{vss}] + Equivalent to + \verb-\vskip 0cm plus 1fil minus 1fil-. + +\item [\cs{kern}] + Add a kern item to the current horizontal or vertical list. + +\item [\cs{lastkern}] + If the last item on the current list was a kern, the size of it. + +\item [\cs{lastskip}] + If the last item on the current list was a~glue, the size of it. + +\item [\cs{unkern}] + If the last item of the current list was a~kern, remove it. + +\item [\cs{unskip}] + If the last item of the current list was a~glue, remove it. + +\item [\cs{removelastskip}] + Macro to append the negative of the \cs{lastskip}. + +\item [\cs{advance}] + Arithmetic command to add to or subtract from + a~\gr{numeric variable}. + +\item [\cs{multiply}] + Arithmetic command to multiply a~\gr{numeric variable}. + +\item [\cs{divide}] + Arithmetic command to divide a~\gr{numeric variable}. + + +\end{inventory} + + + +%\point Definition of \gr{glue} and \gr{dimen} +\section{Definition of \gr{glue} and \gr{dimen}} + +This section gives +the syntax of the quantities +\gr{dimen} and \gr{glue}. +In the next section the practical aspects of glue are treated. + +Unfortunately the terminology for glue is slightly confusing. +The syntactical quantity~\gr{glue} is a dimension (a distance) with +\mdqon +possibly a stretch and/""or shrink component. +\mdqoff +In order to add a glob of `glue' (a white space) to a list one has to +let a \gr{glue} be preceded by commands such as \cs{vskip}. + + +%\spoint Definition of dimensions +\subsection{Definition of dimensions} + +A~\gr{dimen} is what \TeX\ expects to see when +it needs to indicate a dimension; it can be positive or negative. +\begin{disp}\gr{dimen} $\longrightarrow$ \gr{optional signs}% + \gr{unsigned dimen}\end{disp} +The unsigned part of a \gr{dimen} can be +\begin{disp}\gr{unsigned dimen} $\longrightarrow$ \gr{normal dimen} + $|$ \gr{coerced dimen}\nl + \gr{normal dimen} $\longrightarrow$ \gr{internal dimen} + $|$ \gr{factor}\gr{unit of measure}\nl + \gr{coerced dimen} $\longrightarrow$ \gr{internal glue} + \end{disp} +That is, we have the following three cases: +\begin{itemize} \item an \gr{internal dimen}; this is + any register or parameter of \TeX\ that has a \gr{dimen} value: + \begin{disp}\PopIndentLevel\gr{internal dimen} $\longrightarrow$ + \gr{dimen parameter}\nl + \indent $|$ \gr{special dimen} $|$ \cs{lastkern}\nl + \indent $|$ \gr{dimendef token} $|$ \cs{dimen}\gr{8-bit number}\nl + \indent $|$ \cs{fontdimen}\gr{number}\gr{font}\nl + \indent $|$ \gr{box dimension}\gr{8-bit number}\nl + \gr{dimen parameter} $\longrightarrow$ \cs{boxmaxdepth}\nl + \indent $|$ \cs{delimitershortfall} $|$ \cs{displayindent}\nl + \indent $|$ \cs{displaywidth} $|$ \cs{hangindent}\nl + \indent $|$ \cs{hfuzz} $|$ \cs{hoffset} $|$ \cs{hsize}\nl + \indent $|$ \cs{lineskiplimit} $|$ \cs{mathsurround}\nl + \indent $|$ \cs{maxdepth} $|$ \cs{nulldelimiterspace}\nl + \indent $|$ \cs{overfullrule} $|$ \cs{parindent}\nl + \indent $|$ \cs{predisplaysize} $|$ \cs{scriptspace}\nl + \indent $|$ \cs{splitmaxdepth} $|$ \cs{vfuzz}\nl + \indent $|$ \cs{voffset} $|$ \cs{vsize} + \end{disp} +\item a dimension denotation, + consisting of \gr{factor}\gr{unit of measure}, + for example \verb>0.7\vsize>; or +\item an \gr{internal glue} (see below) + coerced to a dimension by omitting + the stretch and shrink components, for example \cs{parfillskip}. +\end{itemize} + +A dimension denotation is a somewhat complicated entity: +\begin{itemize} \item a \gr{factor} is an integer denotation, + a decimal constant denotation (a number with an integral and + a fractional part), + or an \gr{internal integer} + \begin{disp}\PopIndentLevel + \gr{factor} $\longrightarrow$ \gr{normal integer} + $|$ \gr{decimal constant}\nl + \gr{normal integer} $\longrightarrow$ \gr{integer denotation}\nl + \indent $|$ \gr{internal integer}\nl + \gr{decimal constant} $\longrightarrow$ \n{.$_{12}$} + $|$ \n{,$_{12}$}\nl + \indent $|$ \gr{digit}\gr{decimal constant}\nl + \indent $|$ \gr{decimal constant}\gr{digit} + \end{disp} + An internal integer is a parameter that is `really' an +\alt + integer (for instance, \cs{count0}), and not coerced from a dimension or glue. + See Chapter~\ref{number} + for the definition of various kinds of integers. +\item a \gr{unit of measure} can be + a \gr{physical unit}, that is, an ordinary unit such as~\n{cm} + (possibly preceded by \n{true}), + an internal unit such as~\n{em}, but also an \gr{internal integer} + (by conversion to scaled points), + an \gr{internal dimen}, or an \gr{internal glue}. + \begin{disp}\PopIndentLevel + \gr{unit of measure} $\longrightarrow$ + \gr{optional spaces}\gr{internal unit}\nl + \indent $|$ + \gr{optional \n{true}}\gr{physical unit}\gr{one optional space}\nl + \gr{internal unit} $\longrightarrow$ + \n{em}\gr{one optional space}\nl + \indent $|$ \n{ex}\gr{one optional space} + $|$ \gr{internal integer}\nl + \indent $|$ \gr{internal dimen} $|$ \gr{internal glue} + \end{disp} +\end{itemize} + +Some \gr{dimen}s are called \gr{special dimen}s:\label{special:dimen:list} +\begin{disp}\gr{special dimen} $\longrightarrow$ \cs{prevdepth}\nl + \indent $|$ \cs{pagegoal} $|$ \cs{pagetotal} $|$ \cs{pagestretch}\nl + \indent $|$ \cs{pagefilstretch} $|$ \cs{pagefillstretch}\nl + \indent $|$ \cs{pagefilllstretch} $|$ \cs{pageshrink} $|$ \cs{pagedepth} + \end{disp} +An assignment to any of these is +called an \gr{intimate assignment}, and it is automatically +global (see Chapter~\ref{group}). The meaning of these +dimensions is explained in Chapter \ref{page:break}, with the +exception of \cs{prevdepth} which is treated in +Chapter~\ref{baseline}. + +%\spoint Definition of glue +\subsection{Definition of glue} + +A \gr{glue} is either some form of glue variable, or +a glue denotation with explicitly indicated stretch and +shrink. Specifically, +\begin{disp}\gr{glue} $\longrightarrow$ \gr{optional signs}\gr{internal glue} + $|$ \gr{dimen}\gr{stretch}\gr{shrink}\nl + \gr{internal glue} $\longrightarrow$ \gr{glue parameter} + $|$ \cs{lastskip}\nl + \indent $|$ \gr{skipdef token} $|$ \cs{skip}\gr{8-bit number}\nl + \gr{glue parameter} $\longrightarrow$ \cs{abovedisplayshortskip}\nl + \indent $|$ \cs{abovedisplayskip} $|$ \cs{baselineskip}\nl + \indent $|$ \cs{belowdisplayshortskip} $|$ \cs{belowdisplayskip}\nl + \indent $|$ \cs{leftskip} $|$ \cs{lineskip} $|$ \cs{parfillskip} + $|$ \cs{parskip}\nl + \indent $|$ \cs{rightskip} $|$ \cs{spaceskip} + $|$ \cs{splittopskip} $|$ \cs{tabskip}\nl + \indent $|$ \cs{topskip} $|$ \cs{xspaceskip} +\end{disp} +The stretch and shrink components in a glue denotation +are optional, but when both are specified they have to +be given in sequence; they are defined as +\begin{disp} +\gr{stretch} $\longrightarrow$ \n{plus} \gr{dimen} + $|$ \n{plus}\gr{fil dimen} $|$ \gr{optional spaces}\nl +\gr{shrink} $\longrightarrow$ \n{minus} \gr{dimen} + $|$ \n{minus}\gr{fil dimen} $|$ \gr{optional spaces}\nl +\gr{fil dimen} $\longrightarrow$ \gr{optional signs}\gr{factor}% + \gr{fil unit}\gr{optional spaces}\nl +\gr{fil unit} $\longrightarrow$ \n{ $|$ fil $|$ fill $|$ filll} +\end{disp} + +The actual definition of \gr{fil unit} is recursive +(see Chapter~\ref{gramm}), but these are the only valid +possibilities. + +%\spoint Conversion of \gr{glue} to \gr{dimen} +\subsection{Conversion of \gr{glue} to \gr{dimen}} + +The grammar rule +\begin{disp}\gr{dimen} $\longrightarrow$ + \gr{factor}\gr{unit of measure} +\end{disp} +has some noteworthy consequences, caused by the fact +that a \gr{unit of measure} need not look like a `unit of measure' +at all (see the list above). + +For instance, from this definition we conclude that the statement +\begin{verbatim} +\dimen0=\lastpenalty\lastpenalty +\end{verbatim} +is +syntactically correct because \cs{lastpenalty} can function +both as an integer and as \gr{unit of measure} by taking +its value in scaled points. +After \verb>\penalty8> the \cs{dimen0} thus defined will +have a size of~\n{64sp}. + +More importantly, consider the case where the \gr{unit of measure} is +an \gr{internal glue}, that is, any sort of glue parameter. +Prefixing such a glue with a number (the \gr{factor}) +makes it a valid \gr{dimen} specification. +Thus \begin{verbatim} +\skip0=\skip1 +\end{verbatim} +is very different +from \begin{verbatim} +\skip0=1\skip1 +\end{verbatim} +The first statement makes +\cs{skip0} equal to \cs{skip1}, the second converts +the \cs{skip1} to a \gr{dimen} before assigning it. +In other words, the \cs{skip0} defined by the second statement +has no stretch or shrink. + + +%\spoint Registers for \cs{dimen} and \cs{skip} +\subsection{Registers for \cs{dimen} and \cs{skip}} + +\TeX\ has registers for storing \gr{dimen} and \gr{glue} +values: the \csidx{dimen} and \csidx{skip} registers +respectively. These are accessible by the expressions +\begin{disp}\cs{dimen}\gr{number}\end{disp} and +\begin{disp}\cs{skip}\gr{number}\end{disp} +As with all registers of \TeX, these registers are +numbered~0--255. + +Synonyms for registers can be made with the \csidx{dimendef} and +\csidx{skipdef} commands. Their syntax is +\begin{Disp}\cs{dimendef}\gr{control sequence}\gr{equals}\gr{8-bit number} +\end{Disp} +and +\begin{Disp}\cs{skipdef}\gr{control sequence}\gr{equals}\gr{8-bit number}\end{Disp} +For example, after \verb-\skipdef\foo=13- using \cs{foo} +is equivalent to using \cs{skip13}. + +Macros \csidx{newdimen} and \csidx{newskip} exist in plain \TeX +for allocating an unused dimen or skip register. +These macros are defined to be \cs{outer} in the plain format. + +%\spoint Arithmetic: addition +\subsection{Arithmetic: addition} + +As for integer variables, arithmetic operations exist for +\cstoidx advance\par\term glue!arithmetic on\par\term arithmetic! on glue\par +dimen, glue, and muglue (mathematical glue; see page~\pageref{muglue}) +variables. + +The expressions +\begin{Disp}\cs{advance}\gr{dimen variable}\gr{optional \n{by}}% + \gr{dimen}\nl + \cs{advance}\gr{glue variable}\gr{optional \n{by}}% + \gr{glue}\nl + \cs{advance}\gr{muglue variable}\gr{optional \n{by}}% + \gr{muglue}\end{Disp} +add to the size of a dimen, glue, or muglue. + +Advancing a \gr{glue variable} by \gr{glue} is done by +adding the natural sizes, and the stretch and shrink components. +Because \TeX\ converts between \gr{glue} and \gr{dimen}, +it is possible to write for instance +\begin{verbatim} +\advance\skip1 by \dimen1 +\end{verbatim} +or +\begin{verbatim} +\advance\dimen1 by \skip1 +\end{verbatim} +In the first case \cs{dimen1} is coerced to \gr{glue} without +stretch or shrink; in the second case the \cs{skip1} is coerced +to a \gr{dimen} by taking its natural size. + +%\spoint Arithmetic: multiplication and division +\subsection{Arithmetic: multiplication and division} + +Multiplication and division operations exist for glue +\cstoidx multiply\par\cstoidx divide\par +and dimensions. One may for instance write +\begin{verbatim} +\multiply\skip1 by 2 +\end{verbatim} +which multiplies the natural size, and the stretch and shrink +components of \cs{skip1} by~2. + +The second operand of a \cs{multiply} or \cs{divide} +operation can only be a \gr{number}, that is, an integer. +Introducing the notion of \gr{numeric variable}: +\begin{disp}\gr{numeric variable} $\longrightarrow$ \gr{integer variable} + $|$ \gr{dimen variable} \nl + \indent $|$ \gr{glue variable} $|$ \gr{muglue variable}\end{disp} +these operations take the form +\begin{Disp}\cs{multiply}\gr{numeric variable}\gr{optional \n{by}}% +\gr{number}\end{Disp} +and +\begin{Disp}\cs{divide}\gr{numeric variable}\gr{optional \n{by}}% +\gr{number}\end{Disp} + +Glue and dimen can be multiplied by +non-integer quantities: +\begin{verbatim} +\skip1=2.5\skip2 +\dimen1=.78\dimen2 +\end{verbatim} +However, in the first line the \cs{skip2} is first coerced +to a \gr{dimen} value by omitting its stretch and shrink. + +%\point More about dimensions +\section{More about dimensions} + +%\spoint Units of measurement +\subsection{Units of measurement} + +In \TeX\ dimensions can be indicated in +\term units of measurement\par +\begin{description} \item [centimetre] + denoted \n{cm} or +\item [millimetre] + denoted \n{mm}; these are SI~units ({\italic Syst\`eme International + d'Unit\'es}, the + international system of standard units of measurements). +\item [inch] +\n{in}; more common in the Anglo-American world. +One inch is 2.54~centimetres. +\item [pica] + denoted \n{pc}; one pica is 12~points. +\item [point] + denoted \n{pt}; the common system +for Anglo-American printers. One inch is 72.27 points. +\item [didot point] + denoted \n{dd}; the common system for continental European printers. + Furthermore, 1157 didot points are 1238~points. +\item [cicero] + denoted \n{cc}; one cicero is 12~didot points. +\item [big point] + denoted \n{bp}; one inch is 72 big points. +\item [scaled point] + denoted \n{sp}; this is the smallest unit in \TeX, and all measurements + are integral multiples of one scaled point. + There are $65\,536$ scaled points in a~point. +\end{description} + +Decimal fractions can be written using both the +Anglo-American system with the decimal point +(for example, \n{1in}=\n{72.27pt}) +and the continental European system with a decimal +comma; \n{1in}=\n{72,27pt}. + +Internally \TeX\ works with multiples of a smallest +dimension: the scaled point. +Dimensions larger (in absolute value) than $2^{30}-1$\n{sp}, +which is about 5.75~metres or 18.9~feet, are illegal. + +Both the pica system and the didot system are of French +origin: in 1737 the type founder Pierre Simon Fournier +introduced typographical points based on the French foot. +Although at first he introduced a system based on lines and +points, he later took the point as unit: +there are 72 points in an inch, +which is one-twelfth of a foot. +About 1770 another founder, Fran\c{c}ois Ambroise Didot, introduced +points based on the more common, and slightly longer, +`pied du roi'. + +%\spoint Dimension testing +\subsection{Dimension testing} + +Dimensions and natural sizes of glue can be compared with +the \cs{ifdim} test. This takes the form +\begin{disp}\cs{ifdim}\gr{dimen$_1$}\gr{relation}\gr{dimen$_2$}\end{disp} +where the relation can be an \n>, \n<, or~\n= token, +all of category~12. + +%\spoint Defined dimensions +\subsection{Defined dimensions} + +\begin{inventory} +\item [\cs{z@}] + \n{0pt} + +\item [\cs{maxdimen}] + \n{16383.99999pt}; the largest legal dimension. +\end{inventory} + +These \gr{dimen}s are predefined in the plain format; +for instance \begin{verbatim} +\newdimen\z@ \z@=0pt +\end{verbatim} +Using such abbreviations for commonly used dimensions +has at least two advantages. First of all it saves main memory +if such a dimension occurs in a macro: a control sequence +is one token, whereas a string such as \n{0pt} takes three. +Secondly, it saves time in processing, as \TeX\ does not need +to perform conversions to arrive at the correct type of +object. + +Control sequences such as \cs{z@} +are only available to a user who changes the +category code of the `at' sign. Ordinarily, these control sequences +appear only in the macros defined in packages such as the +plain format. + +%\point More about glue +\section{More about glue} + +Glue items can be added to a vertical list with one of the +\alt +commands \csidx{vskip}\gr{glue}, \cs{vfil}, \cs{vfill}, \cs{vss} or +\cs{vfilneg}; +glue items can be added to a horizontal list with one of the +commands \csidx{hskip}\gr{glue}, \cs{hfil}, \cs{hfill}, \cs{hss} or +\cs{hfilneg}. We will now treat the properties of glue. + +%\spoint Stretch and shrink +\subsection{Stretch and shrink} + +In the syntax given above, \gr{glue} was defined as having +\term stretch\par\term shrink\par +\term glue!stretch component of\par\term glue!shrink component of\par +\begin{itemize}\item a `natural size', which is a \gr{dimen}, and optionally +\item a `stretch' and `shrink' component built out of a \gr{fil dimen}. +\end{itemize} + +Each list that \TeX\ builds has amounts of stretch and shrink +(possibly zero), +which are the sum of the +stretch and shrink components of individual pieces of glue in the list. +Stretch and shrink are used if the context in which the list +appears requires it to assume a size that is different from +its natural size. + +There is an important difference in behaviour between stretch +and shrink components when they are finite \ldash that is, +when the \gr{fildimen} is not \n{fil}(\n{l}(\n{l})). +A~finite amount of shrink is indeed the maximum shrink +that \TeX\ will take: the amount of glue specified +as \begin{verbatim} +5pt minus 3pt +\end{verbatim} +can shrink to \n{2pt}, but not further. +In contrast to this, a finite amount of stretch +can be stretched arbitrarily far. +Such arbitrary stretching +has a large `badness', however. +Badness calculation is treated below. + +\begin{example} +The sequence with natural size \n{20pt} +\begin{verbatim} +\hskip 10pt plus 2pt \hskip 10pt plus 3pt +\end{verbatim} +has \n{5pt} of stretch, but it has no shrink. In +\begin{verbatim} +\hskip 10pt minus 2pt \hskip 10pt plus 3pt +\end{verbatim} +there is \n{3pt} of stretch, and \n{2pt} of shrink, +so its minimal size is~\n{18pt}. + +Positive shrink is not the same as negative stretch: +\begin{verbatim} +\hskip 10pt plus -2pt \hskip 10pt plus 3pt +\end{verbatim} +looks a lot like the previous example, but it cannot +be shrunk as there are no \hbox{\n{minus}\gr{dimen}} +specifications. It does have \n{1pt} of stretch, however. + +This is another example of negative amounts of shrink and stretch. +It is not possible to stretch +glue (in the informal sense) by shrinking it (in the technical +sense): \begin{verbatim} +\hbox to 5cm{a\hskip 0cm minus -1fil} +\end{verbatim} +is an underfull box, because \TeX\ looks for a \n{plus}~\gr{dimen} +specification when it needs to stretch the contents. + +Finally, \begin{verbatim} +\hskip 10pt plus -3pt \hskip 10pt plus 3pt +\end{verbatim} +can neither stretch nor shrink. +The fact that there is only stretch +available means that the sequence cannot +shrink. However, the stretch components cancel out: the +total stretch is zero. Another way of looking at this +is to consider that for each point that the second glue item would +stretch, the first one would `stretch back' one point. +\end{example} + +Any amount of infinite stretch or shrink overpowers all +finite stretch or shrink available: +\begin{verbatim} +\hbox to 5cm{\hskip 0cm plus 16384pt + text\hskip 0cm plus 0.0001fil} +\end{verbatim} +has the \n{text} at the extreme left of the box. +There are three orders of `infinity', each one infinitely +stronger than the previous one: +\begin{verbatim} +\hbox to 5cm{\hskip 0cm plus 16384fil + text\hskip 0cm plus 0.0001fill} +\end{verbatim} +and +\begin{verbatim} +\hbox to 5cm{\hskip 0cm plus 16384fill + text\hskip 0cm plus 0.0001filll} +\end{verbatim} +both have the \n{text} at the left end of the box. + + + +%\spoint Glue setting +\subsection{Glue setting} + +In the process of `glue setting', the desired width (or height) +\term glue! setting\par +of a box is compared with the natural dimension of its contents, +which is the sum of all natural dimensions of boxes and globs of glue. +If the two differ, any available stretchability or shrinkability is used +to bridge the gap. +To attain the desired dimension of the box +only the glue of the highest available order is set: +each piece of glue of that order is stretched or shrunk by the +same ratio. + +For example, in +\begin{verbatim} +\hbox to 6pt{\hskip 0pt plus 3pt \hskip 0pt plus 9pt} +\end{verbatim} +the natural size of the box is~\n{0pt}, and +the total stretch is~\n{12pt}. In order to obtain a box +of~\n{6pt} each glue item is set with a stretch ratio +of~$1/2$. Thus the result is equivalent to +\begin{verbatim} +\hbox {\hskip 1.5pt \hskip 4.5pt} +\end{verbatim} +Only the highest order of stretch or shrink is used: +in \begin{verbatim} +\hbox to 6pt{\hskip 0pt plus 1fil \hskip 0pt plus 9pt} +\end{verbatim} +the second glue will assume its natural size of~\n{0pt}, +and only the first glue will be stretched. + +\TeX\ will never exceed the maximum value of a finite +amount of shrink. +A~box that cannot be shrunk enough is called `overfull'. +Finite stretchability can be exceeded to provide an +escape in difficult situations; however, \TeX\ is likely +to give an \verb-Underfull \hbox- message about this +(see page~\pageref{over/underfull}). +For an example of infinite shrink see page~\pageref{rlap}. + +%\spoint Badness +\subsection{Badness} + +When stretching or shrinking a list \TeX\ calculates +\term badness! calculation\par +badness based on the +ratio between actual stretch and the amount of stretch +present in the line. See Chapter~\ref{line:break} +for the application of badness to the paragraph algorithm. + +%\tracingmacros=2 \tracingcommands\tracingmacros +The formula for badness of a list that is stretched (shrunk) is +\label{bad:form}\message{Check roman min} +\begin{disp} $\displaystyle b=\hbox{min}\left(10\,000, +100\times \left({\hbox{actual amount stretched (shrunk)} +\over\hbox{possible amount of stretch (shrink)}}\right)^3\right)$\end{disp} +In reality \TeX\ uses a slightly different formula that is +easier to calculate, but behaves the same. Since glue setting is +one of the main activities of \TeX, this must be performed +as efficiently as possible. + +This formula lets the badness be a reasonably small number +if the glue set ratio (the fraction in the above expression) +is reasonably small, but will let it grow rapidly once +the ratio is more than~1. Badness is infinite if the +glue would have to shrink more than the allotted amount; +stretching glue beyond its maximum is possible, so this +provides an escape for very difficult lines of text or pages. + +In \TeX3, the \cs{badness} parameter records the badness +of the most recently formed box. + +%\spoint Glue and breaking +\subsection{Glue and breaking} + +\TeX\ can break lines and pages in several kinds of places. +One of these places is before a glue item. +The glue is then discarded. For line breaks this is treated +in Chapter~\ref{line:break}, +for page breaks see Chapter~\ref{page:break}. + +There are two macros in plain \TeX, \csidx{hglue} and \csidx{vglue}, +that give non-disappearing glue in horizontal and +vertical mode respectively. For the horizontal case this is +accomplished by +placing: +\begin{verbatim} +\vrule width 0pt \nobreak \hskip ... +\end{verbatim} +Because \TeX\ breaks at the front end of glue, +this glue will always stay attached to the rule, +and will therefore never disappear. +The actual macro definitions are somewhat more complicated, +because they take care to preserve the \cs{spacefactor} and the +\cs{prevdepth}. + +%\spoint \cs{kern} +\subsection{\cs{kern}} + +The \csidx{kern} command specifies +a~kern item in whatever mode \TeX\ is currently +in. A~kern item is much like a glue item without +stretch or shrink. +It differs from glue in that it is +in general not a legal breakpoint. Thus in +\begin{verbatim} +.. text .. \hbox{a}\kern0pt\hbox{b} +\end{verbatim} +\TeX\ will not break lines in between the boxes; in +\begin{verbatim} +.. text .. \hbox{a}\hskip0pt\hbox{b} +\end{verbatim} +a line can be broken in between the boxes. + +However, if a kern is followed by glue, \TeX\ can break at the +kern (provided that it is not in math mode). +In horizontal mode +both the kern and the glue then disappear in the break. +In vertical mode they are discarded when they are moved to +the (empty) current page after the material before +the break has been disposed of by the output routine +(see Chapter~\ref{page:break}). + +%\spoint Glue and modes +\subsection{Glue and modes} + +All horizontal skip commands are \gr{horizontal command}s and +all vertical skip commands are \gr{vertical commands}s. +This means that, for instance, an \cs{hskip} command +makes \TeX\ start a paragraph if it is given in vertical mode. +The \cs{kern} command can be given in both modes. + +%\spoint The last glue item in a list: backspacing +\subsection{The last glue item in a list: backspacing} + +The last glue item in a list can be measured, and +it can be removed in all modes but external vertical mode. +The internal variables +\csidx{lastskip} and \csidx{lastkern} can be used +to measure the last glob of glue in all modes; +if the last glue was not a skip or kern respectively +they give~\n{0pt}. +In math mode the \cs{lastskip} +functions as \gr{internal muglue}, but in general +it classifies as \gr{internal glue}. +The \cs{lastskip} and \cs{lastkern} +are also \n{0pt} if that was the size of the last glue or +kern item on the list. + +The operations\label{unskip} +\csidx{unskip} and \csidx{unkern} remove the last item of a list, +if this is a glue or kern respectively. They have no effect +in external vertical mode; in that case the +best substitute is +\verb=\vskip-\lastskip= +and~\verb=\kern-\lastkern=. + +In the process of paragraph building \TeX\ itself performs +an important \cs{unskip}: a~paragraph ending with a +white line will have a space token inserted by \TeX's input processor. +This is removed by an \cs{unskip} before the \cs{parfillskip} glue +(see Chapter~\ref{par:end}) is inserted. + +Glue is treated by \TeX\ as a special case of leaders, +which becomes apparent when \cs{unskip} is applied to +leaders: they are removed. + +%\spoint Examples of backspacing +\subsection{Examples of backspacing} + +The plain \TeX\ macro \csidx{removelastskip} is defined +as \begin{verbatim} +\ifdim\lastskip=0pt \else \vskip-\lastskip \fi +\end{verbatim} +If the last item on the list was a glue, this macro will +backspace by its value, provided its natural size was not zero. +In all other cases, nothing is added to the list. + +Sometimes an intelligent version of commands such as \cs{vskip} +is necessary, in the sense that two subsequent skip commands +should result only in the larger of the two glue amounts. +On page~\pageref{skip:scheme} such a macro is used: +\begin{verbatim} +\newskip\tempskipa +\def\vspace#1{\tempskipa=#1\relax + \ifvmode \ifdim\tempskipa<\lastskip + \else \vskip-\lastskip \vskip\tempskipa + \fi + \else \vskip\tempskipa \fi} +\end{verbatim} +First of all, this tests whether the mode is vertical; +if not, the argument can safely be placed. +Copying the argument into a skip register is necessary +because \cs{v\-space}\verb>{2pt plus 3pt}> would lead to +problems in an \verb>\ifdim#1<\lastskip> test. + +If the surrounding mode was vertical, the argument +should only be placed if it is not less than what is +already there. The macro would be incorrect +if the test read +\begin{verbatim} + \ifdim\tempskipa>\lastskip + \vskip-\lastskip \vskip\tempskipa + \fi +\end{verbatim} +In this case the sequence +\begin{verbatim} +... last word.\par \vspace{0pt plus 1fil} +\end{verbatim} +would not place any glue, because after +the \cs{par} we are in vertical mode and +\cs{lastskip} has a value of \n{0pt}. + +%\spoint Glue in trace output +\subsection{Glue in trace output} + +If the workings of \TeX\ are traced by setting +\cs{tracingoutput} positive, or if \TeX\ +writes a box to the log file +(because of a \cs{showbox} command, or because it +is overfull or underfull), +glue is denoted by the control sequence \cs{glue}. +This is not a \TeX\ command; it merely indicates the presence +of glue in the current list. + +The box representation that \TeX\ generated from, +\alt +for instance, \cs{showbox} +inserts a space after every explicit \cs{kern}, +but no space is inserted after an implicit +kern that was inserted by the kerning information in the font +\n{tfm} file. Thus \hbox{\verb-\kern 2.0pt-} denotes a kern +that was inserted by the user or by a macro, and +\verb-\kern2.0pt- denotes an implicit kern. + +Glue that is inserted automatically (\cs{topskip}, \cs{baselineskip}, +et cetera) is denoted by name in \TeX's trace output. +For example, the box +\begin{verbatim} +\vbox{\hbox{Vo}\hbox{b}} +\end{verbatim} +looks like +\begin{verbatim} +\vbox(18.83331+0.0)x11.66669 +.\hbox(6.83331+0.0)x11.66669 +..\tenrm V +..\kern-0.83334 +..\tenrm o +.\glue(\baselineskip) 5.05556 +.\hbox(6.94444+0.0)x5.55557 +..\tenrm b +\end{verbatim} +Note the implicit kern inserted between `V' and~`o'. + +%%%% end of input file [glue] + +%\InputFile:rules +%%%% this is input file [rules] +%\subject[rules] Rules and Leaders +\endofchapter +\chapter{Rules and Leaders}\label{rules} + +Rules and leaders are two ways of getting \TeX\ to draw a line. +Leaders are more general than rules: they can also fill +available space with copies of a certain box. This chapter +explain how rules and leaders work, and how they interact with modes. + + +\begin{inventory} +\item [\cs{hrule}] + Rule that spreads in horizontal direction. + +\item [\cs{vrule}] + Rule that spreads in vertical direction. + +\item [\cs{leaders}] + Fill a specified amount of space with a rule or copies of box. + +\item [\cs{cleaders}] + Like \verb=\leaders=, but with box leaders + any excess space is split equally before and after the leaders. + +\item [\cs{xleaders}] + Like \verb=\leaders=, but with box leaders any excess space is + spread equally before, after, and between the boxes. + +\end{inventory} + +%\point Rules +\section{Rules} + +\TeX's rule commands give +\term rules\par +rectangular black patches with horizontal and vertical sides. +Most of the times, a rule command will give output that +looks like a rule, but~\hbox{\vrule height 1.5ex width 1.5ex} +can also be produced by a rule. + +\TeX\ has both horizontal and vertical rules, +but the names do not necessarily imply anything about the shape. +They do, however, imply something about modes: +an \csidx{hrule} command can only be used in vertical mode, +and a \csidx{vrule} only in horizontal mode. +In fact, an \cs{hrule} is a \gr{vertical command}, and a \cs{vrule} +is a \gr{horizontal command}, so \TeX\ may change +modes when encountering these commands. + +Why then is a \cs{vrule} called a {\em vertical\/} rule? +The reason is that a \cs{vrule} can expand arbitrarily +far in the vertical direction: if its height and depth are not +specified explicitly it will take as much room as its +surroundings allow\altt. + +\begin{example} +\begin{verbatim} +\hbox{\vrule\ text \vrule} +\end{verbatim} +looks like \begin{disp}\leavevmode\hbox{\vrule\ text \vrule}\end{disp} +and \begin{verbatim} +\hbox{\vrule\ A gogo! \vrule} +\end{verbatim} +looks like +\begin{disp}\leavevmode\hbox{\vrule\ A gogo! \vrule}\end{disp} +\end{example} + +For the \cs{hrule} command a similar statement is true: +a horizontal rule can spread to assume the width of +its surroundings. Thus +\begin{verbatim} +\vbox{\hbox{One line of text}\hrule} +\end{verbatim} +looks like +\begin{disp}\leavevmode\vtop{\hbox{One line of text}\hrule}\end{disp} + + +%\spoint Rule dimensions +\subsection{Rule dimensions} + +Horizontal and vertical rules have a default thickness: +\begin{Disp} \cs{hrule}\quad is the same as\quad \verb-\hrule height.4pt depth0pt- +\end{Disp} +and +\begin{Disp} \cs{vrule}\quad is the same as\quad \verb-\vrule width.4pt- \end{Disp} +and if the remaining dimension remains unspecified, the rule +extends in that direction to fill the enclosing box. + +Here is the formal specification of how to indicate rule sizes: +\begin{disp}\gr{vertical rule} $\longrightarrow$ + \cs{vrule}\gr{rule specification}\nl + \gr{horizontal rule} $\longrightarrow$ + \cs{hrule}\gr{rule specification}\nl + \gr{rule specification} $\longrightarrow$ + \gr{optional spaces} \nl \indent$|$ + \gr{rule dimensions}\gr{rule specification}\nl + \gr{rule dimension} $\longrightarrow$ + \n{width}\gr{dimen} $|$ \n{height}\gr{dimen} $|$ + \n{depth}\gr{dimen} + \end{disp} +If a rule dimension is specified twice, the second instance +takes precedence over the first. This makes it possible +to override the default dimensions. For instance, +after +\alt +\howto Change the default dimensions of rules\par +\begin{verbatim} +\let\xhrule\hrule \def\hrule{\xhrule height .8pt} +\end{verbatim} +the macro \cs{hrule} gives a horizontal rule +of double the original height, and it is still possible +with \begin{verbatim} +\hrule height 2pt +\end{verbatim} +to specify other heights. + +It is possible to specify all three dimensions; then +\begin{verbatim} +\vrule height1ex depth0pt width1ex +\end{verbatim} +and +\begin{verbatim} +\hrule height1ex depth0pt width1ex +\end{verbatim} +look the same. +Still, each of them can be used only in the appropriate mode. + +%\point Leaders +\section{Leaders} + +Rules are intimately connected to modes, which makes it easy +\term leaders\par +to obtain some effects. For instance, a typical application +of a vertical rule looks like +\begin{verbatim} +\hbox{\vrule width1pt\ Important text! \vrule width 1pt} +\end{verbatim} +which gives +\begin{disp}\leavevmode\hbox{\vrule width 1pt\ Important text! + \vrule width 1pt}\end{disp} +However, one might want to have a horizontal rule +in horizontal mode for effects such as +\begin{disp}\leavevmode +\vbox{\hbox to 5cm{$\longleftarrow$\hfil 5cm\hfil$\longrightarrow$} + \hbox to 5cm{from here\leaders\hrule\hfil to there}}\end{disp} +An \cs{hrule} can not be used in horizontal mode, and +a vertical rule will not spread automatically. + +However, there is a way to use an \cs{hrule} command in +horizontal mode and a \cs{vrule} in vertical mode, +and that is with `leaders', so called because +they lead your eye across the page. +A~leader command tells \TeX\ +to fill a~specified space, in whatever mode it is in, +with as many copies of some box or rule specification +as are needed. For instance, the above example +was given as +\begin{disp}\verb>\hbox to 5cm{from here\leaders\hrule\hfil to there}>\end{disp} +that is, with an \cs{hrule} that was allowed to stretch along +an \cs{hfil}. +Note that the leader was given a horizontal skip, +corresponding to the horizontal mode in which it appeared. + +A general leader command looks like +\begin{Disp} \gr{leaders}\gr{box or rule}% + \gr{vertical/horizontal/mathematical skip}\end{Disp} +where \gr{leaders} is \cs{leaders}, \cs{cleaders}, +or~\cs{xleaders}, a \gr{box~or~rule} +is a~\gr{box}, \cs{vrule}, or~\cs{hrule}, and the +lists of horizontal and vertical skips appear in Chapter~\ref{hvmode}; +a~mathematical skip is either a horizontal skip or an~\cs{mskip} +(see page~\pageref{muglue}). +Leaders can thus be used in all three modes. Of course, the +appropriate kind of skip must be specified. + +A horizontal (vertical) box containing leaders has at least +the height and depth (width) of the \gr{box~or~rule} used +in the leaders, even if, as can happen in the case of box leaders, +no actual leaders are placed. + +%\spoint Rule leaders +\subsection{Rule leaders} + +Rule leaders fill the specified amount of space with a rule +\term leaders !rule\par\cstoidx leaders\par +extending in the direction of the skip specified. +The other dimensions of the resulting rule leader +are determined by the sort of rule that is used: +either dimensions can be specified explicitly, or +the default values can be used. + +For instance, +\begin{verbatim} +\hbox{g\leaders\hrule\hskip20pt f} +\end{verbatim} +gives \begin{disp}\leavevmode\hbox{g\leaders\hrule\hskip20pt f}\end{disp} +because a horizontal rule has a default height of~\n{.4pt}. +On the other hand, +\begin{verbatim} +\hbox{g\leaders\vrule\hskip20pt f} +\end{verbatim} +gives \begin{disp}\leavevmode\hbox{g\leaders\vrule\hskip20pt f}\end{disp} +because the height and depth of a vertical rule +by default fill the surrounding box. + +Spurious rule dimensions are ignored: in horizontal mode +\begin{verbatim} +\leaders\hrule width 10pt \hskip 20pt +\end{verbatim} +is equivalent to +\begin{verbatim} +\leaders\hrule \hskip 20pt +\end{verbatim} + +If the width or height-plus-depth +of either the skip or the box is negative, +\TeX\ uses ordinary glue instead of leaders. + +%\spoint Box leaders +\subsection{Box leaders} + +Box leaders fill the available spaces with copies of +a given box, instead of with a rule. + +\newbox\centerdot \setbox\centerdot=\hbox{\hskip.7em.\hskip.7em} + +For all of the following examples, assume that a box register +has been allocated: +\begin{verbatim} +\newbox\centerdot \setbox\centerdot=\hbox{\hskip.7em.\hskip.7em} +\end{verbatim} +Now the output of +\begin{verbatim} +\hbox to 8cm {here\leaders\copy\centerdot\hfil there} +\end{verbatim} +is +\begin{disp}\leavevmode\hbox to 8cm {here\leaders\copy\centerdot\hfil there} +\end{disp} That is, copies of the box register fill up the +available space. + +Dot leaders, as in the above example, are often used for +tables of contents. In such applications it is desirable that +dots on subsequent lines are vertically aligned. +The \cs{leaders} command does this automatically: +\begin{verbatim} +\hbox to 8cm {here\leaders\copy\centerdot\hfil there} +\hbox to 8cm {over here\leaders\copy\centerdot\hfil over there} +\end{verbatim} +gives \begin{disp}\leavevmode +\vtop{\hbox to 8cm {here\leaders\copy\centerdot\hfil there} +\hbox to 8cm {over here\leaders\copy\centerdot\hfil over there\strut}} +\end{disp} +The mechanism behind this is the following: +\TeX\ acts as if an infinite row of boxes starts (invisibly) at +the left edge of the surrounding box, +and the row of copies actually placed is +merely the part of this row that is not obscured by +the other contents of the box. + +Stated differently, box leaders are a window on an infinite +row of boxes, and the row starts at the left edge of the +surrounding box. Consider the following example: +\begin{verbatim} +\hbox to 8cm {\leaders\copy\centerdot\hfil} +\hbox to 8cm {word\leaders\copy\centerdot\hfil} +\end{verbatim} +which gives +\begin{disp}\leavevmode\vtop{\hbox to 8cm {\leaders\copy\centerdot\hfil} +\hbox to 8cm {word\leaders\copy\centerdot\hfil\strut}}\end{disp} +The row of leaders boxes becomes visible as soon as it +does not coincide with other material. + +The above discussion only talked about leaders in horizontal +mode. Leaders can equally well be placed in vertical mode; +for box leaders the `infinite row' then starts at the top +of the surrounding box. + +%\spoint Evenly spaced leaders +\subsection{Evenly spaced leaders} + +Aligning subsequent box leaders in the way described above +means that the white space before and after the +leaders will in general be different. +If vertical alignment is not +an issue it may be aesthetically more pleasing to have +the leaders evenly spaced. +The \csidx{cleaders} command is like \cs{leaders}, +except that it splits excess space before and after the leaders +into two equal parts, centring the row of boxes in the +available space. + +\begin{example}\message{check verbatim indentation} +\begin{verbatim} +\hbox to 7.8cm {here\cleaders\copy\centerdot\hfil there} +\hbox to 7.8cm {here is\cleaders\copy\centerdot\hfil there} +\end{verbatim} +gives \begin{disp}\leavevmode\vbox{ +\hbox to 7.8cm {here\cleaders\copy\centerdot\hfil there} +\hbox to 7.8cm {here is\cleaders\copy\centerdot\hfil there\strut} +}\end{disp} +The `expanding leaders' \csidx{xleaders} spread excess space evenly +between the boxes, with equal globs of glue before, after, +and in between leader boxes. +\end{example} + +\begin{example} \begin{verbatim} +\hbox to 7.8cm{here\hskip.7em + \xleaders\copy\centerdot\hfil \hskip.7em there} +\end{verbatim} +gives \begin{disp}\leavevmode +\hbox to 7.8cm {here\hskip.7em\xleaders\copy\centerdot\hfil\hskip.7em there} +\end{disp} Note that the glue in the leader box is balanced here +with explicit glue before and after the leaders; +leaving out these glue items, as in\begin{verbatim} +\hbox to 7.8cm {here\xleaders\copy\centerdot\hfil there} +\end{verbatim} +gives \begin{disp}\leavevmode +\hbox to 7.8cm {here\xleaders\copy\centerdot\hfil there} +\end{disp} +which is clearly not what was intended. +\end{example} + +%\point Assorted remarks +\section{Assorted remarks} + +%\spoint Rules and modes +\subsection{Rules and modes} + +Above it was explained how rules can only occur in the +appropriate modes. Rules also influence mode-specific +quantities: +no baselineskip is added before rules in +vertical mode. In order to prevent glue after rules, +\TeX\ sets \cs{prevdepth} to +\n{\hbox{-}1000pt} +(see Chapter~\ref{baseline}). +Similarly the \cs{spacefactor} is set to 1000 after a \cs{vrule} +in horizontal mode (see Chapter~\ref{line:break}). + + +%\spoint[par:leaders:end] Ending a paragraph with leaders +\subsection{Ending a paragraph with leaders} +\label{par:leaders:end} + +An attempt to simulate an \cs{hrule} at the end of a paragraph by +\howto End a paragraph with leaders\par +\begin{verbatim} +\nobreak\leaders\hrule\hfill\par +\end{verbatim} +does not work. The reason for this is that \TeX\ +performs an \cs{unskip} at the end of a paragraph, +which removes the leaders. Normally this \cs{unskip} removes +any space token inserted by the input processor after the +last line. Remedy: stick an \verb.\hbox{}. at the end of +the leaders. + +%\spoint Leaders and box registers +\subsection{Leaders and box registers} + +In the above examples the leader box was inserted with +\cs{copy}. The output of +\begin{verbatim} +\hbox to 8cm {here\leaders\box\centerdot\hfil there} +\hbox to 8cm {over here\leaders\box\centerdot\hfil + over there} +\end{verbatim} +is +\begin{disp}\leavevmode + \vtop{\hbox to 8cm {here\leaders\box\centerdot\hfil there} + \hbox to 8cm {over here\leaders\box\centerdot\hfil over there} + }\end{disp} +The box register is emptied after the first leader command, +but more than one copy is placed in that first command. + +%\spoint Output in leader boxes +\subsection{Output in leader boxes} + +Any \cs{write}, \cs{openout}, or \cs{closeout} operation +appearing in leader boxes is ignored. +Otherwise such an operation would be executed once for every +copy of the box that would be shipped out. + +%\spoint Box leaders in trace output +\subsection{Box leaders in trace output} + +The dumped box representation obtained from, +for instance, \cs{tracingoutput} +does not write out box leaders in full: only the total size and +one copy of the box used are dumped. In particular, +the surrounding white space before and after the leaders +is not indicated. + +%\spoint Leaders and shifted margins +\subsection{Leaders and shifted margins} + +If margins have been shifted, +leaders may look different +depending on how the shift has been realized. +For an illustration of how \cs{hangindent} and \cs{leftskip} +influence the look of leaders, consider the following +examples, where +\begin{verbatim} +\setbox0=\hbox{K o } +\end{verbatim} +The horizontal boxes above the leaders +\altt +serve to indicate the starting point of the row of leaders. + +First +\begin{verbatim} +\hbox{\leaders\copy0\hskip5cm} +\noindent\advance\leftskip 1em + \leaders\copy0\hskip5cm\hbox{}\par +\end{verbatim} +gives\message{examples on} +\begin{disp}\leavevmode\vbox{\leftskip=0pt \hsize=7cm +\setbox0=\hbox{K o } +\hbox{\leaders\copy0\hskip5cm} +\noindent\advance\leftskip 1em + \leaders\copy0\hskip5cm\hbox{}\par + }\end{disp} +Then +\begin{verbatim} +\hbox{\kern1em\hbox{\leaders\copy0\hskip5cm}} +\hangindent=1em \hangafter=-1 \noindent + \leaders\copy0\hskip5cm\hbox{}\par +\end{verbatim} +gives (note the shift with respect to the previous example) +\begin{disp}\leavevmode\vbox{\leftskip=0pt \hsize=7cm +\setbox0=\hbox{K o } +\hbox{\kern1em\hbox{\leaders\copy0\hskip5cm}} +\hangindent=1em \hangafter=-1 \noindent + \leaders\copy0\hskip5cm\hbox{}\par}\end{disp} +\message{one page} +In the first paragraph the \cs{leftskip} glue only obscures +the first leader box; in the second paragraph the hanging +indentation actually shifts the orientation point for the +row of leaders. Hanging indentation is performed in \TeX\ +by a \cs{moveright} of the boxes containing the lines +of the paragraph. + +%%%% end of input file [rules] + +%\InputFile:group +%%%% this is input file [group] +%\subject[group] Grouping +\endofchapter +\chapter{Grouping}\label{group} + +\TeX\ has a grouping mechanism that is able to confine most +changes to a~particular locality. This chapter explains +what sort of actions can be local, and how groups are formed. + + +\begin{inventory} +\item [\cs{bgroup}] +Implicit beginning of group character. +\item [\cs{egroup}] +Implicit end of group character. +\item [\cs{begingroup}] +Open a group that must be closed with \cs{endgroup}. +\item [\cs{endgroup}] +Close a group that was opened with \cs{begingroup}. +\item [\cs{aftergroup}] +Save the next token for insertion after the current group ends. +\item [\cs{global}] +Make assignments, macro definitions, and arithmetic global. +\item [\cs{globaldefs}] +Parameter for overriding \cs{global} prefixes. +\IniTeX\ default:~0. +\end{inventory} + +%\point The grouping mechanism +\section{The grouping mechanism} + +A group is a sequence of tokens starting with a +\term grouping\par +`beginning of group' token, +and ending with an `end of group' +token, and in which all such tokens are properly balanced. + +The grouping mechanism of \TeX\ is not the same as +the block structure +of ordinary programming languages. +Most languages with block structure are only able to have +local definitions. \TeX's grouping mechanism is stronger: +most assignments made inside a group +are local to that group unless explicitly indicated otherwise, +and outside the group old values are restored. + +An example of local definitions +\begin{verbatim} +{\def\a{b}}\a +\end{verbatim} +gives an `undefined control sequence' +message because \cs{a} is only defined inside the group. +Similarly, the code +\begin{verbatim} +\count0=1 {\count0=2 } \showthe\count0 +\end{verbatim} +will display the value~1; the assignment made inside the group +is undone at the end of the group. + + +Bookkeeping of values that are to be restored outside the group +is done through the mechanism +\term save stack\par +of the `save stack'. Overflow of the save stack is treated +in Chapter~\ref{error}. The save stack is also used for +a few other purposes: in calls such as \hbox{\verb>\hbox to 100pt{...}>} +the specification \hbox{\n{to 100pt}} is put on the save +stack before a new level of grouping is opened. + +In order to prevent a lot of trouble with the save stack, +\IniTeX\ does not allow dumping a format inside a group. +The \cs{end} command is allowed to occur inside a group, +but \TeX\ will give a diagnostic message about this. + +The \cs{aftergroup} control sequence saves a token for +insertion after the current group. Several tokens can be +set aside by this command, and they are inserted in the left-to-right +order in which they were stated. +This is treated in Chapter~\ref{expand}. + + +%\point[global:assign] Local and global assignments +\section{Local and global assignments} +\label{global:assign} + +An assignment or macro definition +is usually made global by prefixing it with \csidx{global}, +\term statements !local\par\term statements !global\par +\term local statements\par\term global statements\par +but non-zero values of the \gr{integer parameter} +\csidx{globaldefs} override \cs{global} +specifications: if \cs{globaldefs} is positive every assignment +is implicitly prefixed with \cs{global}, and if +\cs{globaldefs} is negative, \cs{global} is +ignored. Ordinarily this parameter is zero. + +Some assignment are always global: the \gr{global assignment}s are +\begin{description}%\FlushRight:no +\item [\gr{font assignment}] +assignments involving \cs{fontdimen}, \cs{hyphenchar}, +and \cs{skew\-char}. +\item [\gr{hyphenation assignment}] +\cs{hyphenation} and \cs{patterns} commands +(see Chapter~\ref{line:break}). +\item [\gr{box size assignment}] +altering box dimensions with \cs{ht}, \cs{dp}, and~\cs{wd} +(see Chapter~\ref{boxes}). +\item [\gr{interaction mode assignment}] +run modes for a \TeX\ job (see Chapter~\ref{run}). +\item [\gr{intimate assignment}] +assignments to a \gr{special integer} or \gr{special dimen}; +see %Chapters \ref{number} and~\ref{glue}. +pages \pageref{special:int:list} and~\pageref{special:dimen:list}. +\end{description} + +%\point Group delimiters +\section{Group delimiters} + +A group can be delimited by character tokens of category code~1 +\term delimiter! group\par +for `beginning of group' and code~2 for `end of group', or +control sequence tokens that are \cs{let} to such characters, +the \cs{bgroup} and \cs{egroup} in plain \TeX. +Implicit and explicit braces can match to delimit +a group. + +Groups can also be delimited by \csidx{begingroup} and +\csidx{endgroup}. These two control sequences must +be used together: they cannot be matched with implicit +or explicit braces, nor can they function as the braces +surrounding, for instance, boxed material. + +Delimiting with \cs{begingroup} and \cs{endgroup} can +\label{begin:end:macros}% +provide a limited form of run-time error checking. +In between these two group delimiters an excess +open or close brace would result in +\begin{verbatim} +\begingroup ... } ... \endgroup +\end{verbatim} +or +\begin{verbatim} +\begingroup ... { ... \endgroup +\end{verbatim} +In both cases \TeX\ gives an error message about improper +balancing. Using \cs{bgroup} and \cs{egroup} here would +make an error much harder to find, because of the incorrect +matching that would occur. This idea is used in the environment +macros of several formats. + +The choice of the brace characters for the beginning and end of group +characters is not hard-wired in \TeX. It is arranged +\cstoidx bgroup\par\cstoidx egroup\par +like this in the plain format: +\begin{verbatim} +\catcode`\{=1 % left brace is begin-group character +\catcode`\}=2 % right brace is end-group character +\end{verbatim} +Implicit braces have also been defined in the plain format: +\begin{verbatim} +\let\bgroup={ \let\egroup=} +\end{verbatim} + +Special cases are the following: +\begin{itemize} \item The replacement text of a macro must be enclosed +in explicit beginning and end of group character tokens. +\item The open and close braces for boxes, \cs{vadjust}, +and \cs{insert} can be implicit. This makes it possible +to define, for instance +\begin{verbatim} +\def\openbox#1{\setbox#1=\hbox\bgroup} +\def\closebox#1{\egroup\box#1} +\openbox{15}Foo bar\closebox{15} +\end{verbatim} +\item The right-hand side of a token list assignment and the +argument of the commands \cs{write}, \cs{message}, \cs{errmessage}, +\cs{uppercase}, \cs{lowercase}, +\cs{special}, and \cs{mark} is a \gr{general text}, defined +as +\begin{Disp} \gr{general text} $\longrightarrow$ \gr{filler}\lb + \gr{balanced text}\gr{right brace}\end{Disp} +meaning that the left brace can be implicit, but the closing +right brace must be an explicit character token with category +code~2. \end{itemize} + +In cases where an implicit left brace suffices, and where +expansion is not explicitly inhibited, \TeX\ will +expand tokens until a left brace is encountered. This +is the basis for such constructs as +\verb=\uppercase\expandafter{\romannumeral80}=, +which in this unexpanded form do not adhere to the +syntax. If the first unexpandable token is not a left +brace \TeX\ gives an error message. + +The grammar of \TeX\ (see Chapter~\ref{gramm}) uses +\gr{left brace} and \gr{right brace} for explicit +characters, that is, character tokens, +and \n{\lb} and~\n{\rb} +for possibly implicit characters, +\altt +that is, control sequences that have been \cs{let} to such +explicit characters. + +%\point More about braces +\section{More about braces} + + +%\spoint Brace counters +\subsection{Brace counters} + +\TeX\ has two counters for keeping track of grouping levels: +\term braces\par +the {\it master counter} and the {\it balance counter}. +Both of these counters are syntactic counters: they count the +explicit brace character tokens, but are not affected by implicit +braces (such as \cs{bgroup}) that are semantically equivalent +to an explicit brace. + +The balance counter handles braces in all cases except in +alignment. Its workings are intuitively clear: it goes up +by one for every opening and down for every closing +brace that is not being skipped. Thus +\begin{verbatim} +\iffalse{\fi +\end{verbatim} +increases the balance counter if +this statement is merely scanned (for instance if it +appears in a macro definition text); if this statement +is executed the brace is skipped, so there is no effect on +the balance counter. + +The master counter is more tricky; +it is used in alignments instead of the balance counter. +This counter records all braces, even when they are skipped +such as in \verb>\iffalse{\fi>. +For this counter uncounted skipped braces are still possible: +the alphabetic constants \n{`\lb} and \n{`\rb} have +no effect on this counter when they are +use by the execution processor as a~\gr{number}; +they do affect this counter when they are seen by the +input processor (which merely sees characters, and not +the context). + +%\spoint The brace as a token +\subsection{The brace as a token} + +Explicit braces are character tokens, and as such they are +unexpandable. This implies that they survive until the +last stages of \TeX\ processing. For example, +\begin{verbatim} +\count255=1{2} +\end{verbatim} +will assign~1 to \cs{count255}, +and print~`2', because the +opening brace functions as a delimiter for the number~1. +Similarly \begin{verbatim} +f{f} +\end{verbatim} +will prevent \TeX\ from forming +an `\hbox{ff}' ligature. + +From the fact that braces are unexpandable, +it follows that their nesting is independent +of the nesting of conditionals. For instance +\begin{verbatim} +\iftrue{\else}\fi +\end{verbatim} +will give an open brace, +as conditionals are handled by expansion. The closing +brace is simply skipped as part of the \gr{false text}; +any consequences it has for grouping only come into +play in a later stage of \TeX\ processing. + +Undelimited macro arguments are either single tokens +or groups of tokens enclosed in explicit braces. +Thus it is not possible for an explicit open or close brace +to be a macro argument. However, braces can be assigned +with \cs{let}, for instance as in \begin{verbatim} +\let\bgroup={ +\end{verbatim} +This is used in the plain \cs{footnote} macro +(see page~\pageref{footnote:ex}). + +%\spoint \csc{\char 123} and \csc{\char 125} +\subsection{Open and closing brace control symbols} +% \csc{\char 123} and \csc{\char 125}} + +The control sequences \verb-\{- and \verb-\}- do not really belong +\cstoidx\char123\par\cstoidx\char125\par +in this chapter, not being concerned with grouping. +They have been defined with \cs{let} as synonyms of +\cs{lbrace} and \cs{rbrace} respectively, +and these control sequences are \cs{delimiter} instructions +(see Chapter~\ref{mathchar}). + +The Computer Modern Roman font has no braces, but there are +braces in the typewriter font, and for mathematics +there are braces of different sizes \ldash and extendable ones \rdash in +the extension font. + +%%%% end of input file [group] + +%\InputFile:macro +%%%% this is input file [macro] +%\subject[macro] Macros +\endofchapter +\chapter{Macros}\label{macro} + +Macros are \TeX's abbreviation mechanism for sequences of commands +that are needed more than once, +somewhat like procedures in ordinary programming languages. +\TeX's parameter mechanism, however, is quite unusual. +This chapter explains how \TeX\ macros work. It also +treats the commands \cs{let} and~\cs{futurelet}. + +\begin{inventory} +\item [\cs{def}] + Start a macro definition. + +\item [\cs{gdef}] + Synonym for \verb-\global\def-. + +\item [\cs{edef}] + Start a macro definition; + the replacement text is expanded at definition time. + This command is treated also in the next chapter. + +\item [\cs{xdef}] + Synonym for \verb-\global\edef-. + +\item [\cs{csname}] + Start forming the name of a control sequence. + +\item [\cs{endcsname}] + Stop forming the name of a control sequence. + +\item [\cs{global}] + Make the next definition, arithmetic statement, + or assignment global. + +\item [\cs{outer}] + Prefix indicating that the macro being defined + can be used on the `outer' level only. + +\item [\cs{long}] + Prefix indicating that the arguments of the macro being defined + may contain \cs{par} tokens. + +\item [\cs{let}] + Define a control sequence to be equivalent to the next token. + +\item [\cs{futurelet}] + Define a control sequence to be equivalent to + the token after the next token. + +\end{inventory} + +%\point Introduction +\section{Introduction} + +A macro is basically a sequence of tokens that has +\term macro\par +been abbreviated into a control sequence. +Statements starting with (among others) \cs{def} +are called {\italic macro definitions}\alt, and +writing \begin{verbatim} +\def\abc{\de f\g} +\end{verbatim} +defines the macro \cs{abc}, +with the {\italic replacement text\/} \verb>\de f\g>. +Macros can be used in this way to abbreviate +pieces of text or sequences of commands +that have to be given more than once. +Any time that \TeX's expansion processor +encounters the control sequence \cs{abc}, +it replaces it by the replacement text. + +If a macro should be sensitive to the context +where it is used, it can be defined with parameters: +\begin{verbatim} +\def\PickTwo#1#2{(#1,#2)} +\end{verbatim} +takes two arguments and reproduces them in parentheses. +The call \cs{PickTwo 12} gives `(1,2)'. + +The activity of substituting the replacement text +for a macro is called {\italic macro expansion}. + +%\point Layout of a macro definition +\section{Layout of a macro definition} + +A macro definition consists of, in sequence, +\term definition !macro\par +\begin{enumerate} \item any number of \cs{global}, +\cs{long}, and \cs{outer} prefixes, +\item a \gr{def} control sequence, or anything +that has been \cs{let} to one, +\item a control sequence or active character to be defined, +\item possibly a \gr{parameter text} specifying among other things +how many parameters the macro has, and +\item a replacement text enclosed in explicit character tokens +with category codes 1 and~2, by default \verb-{- and~\verb-}- +in plain \TeX. +\end{enumerate} + +After a macro definition is completed, any saved \cs{afterassignment} +token (see section~\ref{sec:afterassignment}) is inserted. + +The `expanding' definitions \cs{edef} and \cs{xdef} +are treated in Chapter~\ref{expand}. + +%\point Prefixes +\section{Prefixes} + +There are three prefixes that alter the status of the +\term prefixes !macro\par +macro definition: \begin{description} +\item [\csidx{global}] +If the definition occurs inside a group, this prefix +makes the definition global. +This prefix can also be used for assignments other than +macro definitions; in fact, +for macro definitions abbreviations exist obviating the +use of \cs{global}: +\begin{disp}\verb>\gdef\foo...>\quad is equivalent to\quad \verb>\global\def\foo...> +\end{disp} and +\begin{disp}\verb>\xdef\foo...>\quad is equivalent to\quad \verb>\global\edef\foo...> +\end{disp} + +If the parameter \cs{globaldefs} +is positive, all assignments are +implicitly global; +if \cs{globaldefs} is negative any \cs{global} prefixes are +ignored, +and \cs{gdef} and \cs{xdef} make local definitions +(see Chapter~\ref{group}). + +\item [\cs{outer}] +The mechanism of `outer' macros is supposed to facilitate +\term macro !outer\par\cstoidx outer\par +locating (among other errors) unbalanced braces: an \cs{outer} +macro is supposed +to appear only in non-embedded contexts. +To be precise, it is not allowed to occur +\begin{itemize} +\item in macro replacement texts (but it can appear in + for instance \cs{edef} after + \cs{noexpand}, and after \cs{meaning}), +\item in parameter texts, +\item in skipped conditional text, +\item in alignment preambles, and +\item in the \gram{balanced text} of a \cs{message}, \cs{write}, +et cetera. \end{itemize} +For certain applications, however, it is inconvenient +that some of the plain macros are outer, +in particular macros such as \cs{newskip}. One remedy is to +redefine them, without the `outer' option, which +is done for instance in \LaTeX, but cleverer tricks are possible. + +\item [\cs{long}] +Ordinarily, macro parameters are not supposed to contain +\cstoidx long\par +\cs{par} tokens. This restriction is useful (much more so +than the \cs{outer} definitions) in locating +forgotten closing braces. +For example, \TeX\ will complain about a `runaway argument' +\message{Example on} +in the following sequence:\begin{verbatim} +\def\a#1{ ... #1 ... } +\a {This sentence should be in braces. + +And this is not supposed to be part of the argument +\end{verbatim} +\message{one page} +The empty line generates a \cs{par}, which most of the times +means that a closing brace has been forgotten. + +If arguments to a particular macro should be allowed +to contain \cs{par} tokens, then the macro must be declared +to be \cs{long}. \end{description} + +The \cs{ifx} test for equality of tokens +(see Chapter~\ref{if}) takes prefixes into +account when testing whether two tokens have the same definition. + +\begin{comment} +With a little ingenuity it is possible +for \cs{par} tokens to sneak into macro arguments anyway. +Consider the example +\begin{verbatim} +\def\a#1\par!{ ... } +\a bc\par ef\par! +\end{verbatim} +Here the macro \cs{a} is not \cs{long}, but the argument +is \verb>bc\par ef>, which contains a \cs{par} token. +However, +this is of no importance in general. +\end{comment} + +%\point The definition type +\section{The definition type} + +There are four \gr{def} control sequences in \TeX: +\csidx{def}, \csidx{gdef}, \csidx{edef}, and \csidx{xdef}. +The control sequence +\alt +\cs{gdef} is a synonym for \verb>\global\def> and +\cs{xdef} is a synonym for \verb>\global\edef>. +The `expanding definition' \cs{edef} is treated in +Chapter~\ref{expand}. + +The difference between the various types of macro definitions +is only relevant at the time of the definition. +When a macro is called there is no way of telling how +it was defined. + +%\point[param:text] The parameter text +\section{The parameter text} +\label{param:text} + +Between the control sequence or active character to be defined +\term parameter\par\term argument\par +and the opening brace of the replacement text, a \gr{parameter +text} can occur. This specifies whether the macro has parameters, +how many, and how they are delimited. +The \gr{parameter text} cannot contain +explicit braces. + +A macro can have at most nine parameters. +A~parameter is indicated by a parameter token, +consisting of a macro parameter character +(that is, a character of category code~6, in plain \TeX~\verb=#=) +followed by a digit~\n1--\n9. +For instance, \verb>#6>~denotes the sixth parameter of a macro. +Parameter tokens cannot appear outside the context +of a macro definition. + +In the parameter text, +parameters must be numbered consecutively, starting at~1. +A~space after a parameter token is significant, +both in the parameter text and the replacement text. + +Parameters can be delimited or undelimited. A~parameter +is called undelimited if it is followed immediately +by another parameter in the \gr{parameter text} +or by the opening brace of the replacement text; +it is called delimited if it is followed by any other token. + +The tokens (zero or more) that are substituted for +a parameter when a macro is expanded (or `called') +are called +the `argument' corresponding to that parameter. + +%\spoint Undelimited parameters +\subsection{Undelimited parameters} + +When a macro with an undelimited parameter, for instance +\term parameter !undelimited\par +a macro \cs{foo} with one parameter +\begin{verbatim} +\def\foo#1{ ... #1 ...} +\end{verbatim} +is expanded, \TeX\ scans ahead (without expanding) +until a non-blank token is found. +If this token is not an explicit \gr{left brace}, +it is taken to be the argument +corresponding to the parameter. Otherwise a \gr{balanced text} +is absorbed by scanning until the matching explicit +\gr{right brace} has been found. +This balanced text then +constitutes the argument. + +An example with three undelimited parameters follows: with +\begin{verbatim} +\def\foo#1#2#3{#1(#2)#3} +\end{verbatim} +the macro call \cs{foo123} gives `\hbox{1(2)3}'; +but \hbox{\verb-\foo 1 2 3-} also gives the same result. +In the call +\begin{disp}\cs{foo}\n{\char32 1\char32 2\char 32 3}\end{disp} +the first space is skipped in the input processor of \TeX. +The argument corresponding to the first parameter is then +the~\n1. In order to find the second parameter \TeX\ then +skips all blanks, in this case exactly one. As second +parameter \TeX\ finds then the~\n2. Similarly the third +parameter is~\n3. + + +In order to pass several tokens as one undelimited argument +one can use braces. With the above definition of \cs{foo} +the call \verb>\foo a{bc}d> gives `\hbox{a(bc)d}'. +When the argument of a macro is a balanced text instead of +a single token, the delimiting braces are not inserted when +the argument is +inserted in the replacement text. +For example:\begin{verbatim} +\def\foo#1{\count0=1#1\relax} +\foo{23} +\end{verbatim} +will expand to \verb>\count0=123\relax>, +which assigns the value of 123 to the counter. +On the other hand, the statement \begin{verbatim} +\count0=1{23} +\end{verbatim} +would +assign~1 and print~23. + +%\spoint Delimited parameters +\subsection{Delimited parameters} + +Apart from enclosing it in braces there is another way +\term parameter !delimited\par +to pass a sequence of tokens as a single argument to a macro, +namely by using delimited parameters. + +Any non-parameter tokens in the \gr{parameter text} occurring +after a macro parameter (that is, after the parameter number +following the parameter character) +act as a delimiter for that parameter. This includes space tokens: +a space after a parameter number is significant. +Delimiting tokens can also occur between the control +sequence being defined and the first parameter token~\verb>#1>. + +Character tokens acting as delimiters in the parameter text +have both their character code and +category code stored; the delimiting character tokens of the +actual arguments have to match both. +Category codes of such characters may include some that +can normally only appear in special contexts; for instance, after +the definition \begin{verbatim} +\def\foo#1_#2^{...} +\end{verbatim} +the macro \cs{foo} +can be used outside math mode. + +When looking for the argument corresponding to +a delimited parameter, \TeX\ absorbs all tokens without expansion (but +balancing braces) until the +(exact sequence of) delimiting tokens is encountered. +The delimiting tokens are not part of the argument; +they are removed from the input stream during the macro call. + +%\spoint Examples with delimited arguments +\subsection{Examples with delimited arguments} + +As a simple example, \begin{verbatim} +\def\DoASentence#1#2.{{#1#2.}} +\end{verbatim} +defines a macro with an undelimited first parameter, +and a second parameter delimited by a period. +In the call\begin{verbatim} +\DoASentence \bf This sentence is the argument. +\end{verbatim} +the arguments are: +\begin{verbatim} +#1<-\bf +#2<-This sentence is the argument +\end{verbatim} +Note that the closing period is not in the argument, but it has +been absorbed; it is no longer in the input stream. + +A~commonly used delimiter is \cs{par}: +\begin{verbatim} +\def\section#1. #2\par{\medskip\noindent {\bf#1. #2\par}} +\end{verbatim} +This macro has a first parameter that is delimited by~`\n{.\char32}', +and a second parameter that is delimited by \cs{par}. +The call\message{example on one page} +\begin{verbatim} +\section 2.5. Some title + +The text of the section... +\end{verbatim} +will give +\begin{disp}\verb>#1<-2.5>\nl +\verb>#2<-Some title>\n{\char32}\end{disp} +Note that there is a space at the end of the second argument +generated by the line end. If this space is unwanted one might +define \begin{verbatim} +\def\section#1. #2 \par{...} +\end{verbatim} +with \n{\char32}\cs{par} delimiting the second +argument. This approach, however, +precludes the user's writing the \cs{par} explicitly: +\begin{verbatim} +\section 2.5 Some title\par +\end{verbatim} +One way out of this dilemma is to write +\verb>#2\unskip> on all places in the definition text +where the trailing space would be unwanted. + +Control sequences acting as delimiters need not be defined, +as they are absorbed without expansion. Thus +\begin{verbatim} +\def\control#1\sequence{...} +\end{verbatim} +is a useful +definition, even if \cs{sequence} is undefined. + +The importance of category codes in delimited arguments +is shown by the following example: +\begin{verbatim} +\def\a#1 #2.{ ... } +\catcode`\ =12 +\a b c +d. +\end{verbatim} +which gives +\begin{verbatim} +\a #1 #2.-> ... +#1<- b c +#2<-d +\end{verbatim} +Explanation: the delimiter between parameters 1 and~2 is a space +of category~10. In between \n{a} and \n{b} there is a space +of category~12; the first space of category~10 +is the space that is generated by the line end. + +For a `real-life' application of matching of category codes, +see the explanation of \cs{newif} in Chapter~\ref{if}, +and the example on page~\pageref{ex:jobnumber}. + + +%\spoint Empty arguments +\subsection{Empty arguments} + +If the user specifies a \gr{balanced text} in braces +when \TeX\ expects a macro +argument, that text is used as the argument. +Thus, specifying \verb-{}- will give an argument that is +an empty list of tokens; this is called an `empty argument'. + +Empty arguments can also arise from the use of delimited +parameters. For example, after the definition +\begin{verbatim} +\def\mac#1\ro{ ... } +\end{verbatim} +the call +\begin{verbatim} +\mac\ro +\end{verbatim} +will give an empty argument. + +\begin{comment} +However, only +one empty argument can be created this way: +if the macro had been defined as +\begin{verbatim} +\def\mac#1#2\ro{ ... } +\end{verbatim} +the same call +\begin{verbatim} +\mac\ro \othermacro \stillothermacro +\end{verbatim} +will probably cause a `\n{Runaway argument?}' error message. +Explanation: the first parameter is undelimited, so the corresponding +argument is `\cs{ro}'; after that \TeX\ starts looking for a list +of tokens delimited by~\cs{ro}. +\end{comment} + +%\spoint The macro parameter character +\subsection{The macro parameter character} + +When \TeX's input processor scans a macro definition text, +\term character !parameter\par +it inserts a parameter token for any +occurrence of a macro parameter character followed by a digit. +In effect, a parameter token in the replacement text +states `insert parameter number such and such here'. +Two parameter characters in a row are replaced by a single one. + +The latter fact can be used for nested macro definitions. +\label{nest:def}\howto Nested macro definitions\par +Thus \begin{verbatim} +\def\a{\def\b#1{...}} +\end{verbatim} +gives an error message +because \cs{a} was defined without parameters, and +yet there is a parameter token in its replacement text. + +The following +\begin{verbatim} +\def\a#1{\def\b#1{...}} +\end{verbatim} +defines a macro \cs{a} that +defines a macro \cs{b}. However, \cs{b} still does not +have any parameters: the call +\begin{verbatim} +\a z +\end{verbatim} +defines a macro \cs{b} without parameters, +that has to be followed by a~\n z. +Note that this +does not attempt to define a macro \cs{bz}, because the +control sequence \cs{b} has already been formed in \TeX's +input processor when that input line was read. + +Finally, +\begin{verbatim} +\def\a{\def\b##1{...}} +\end{verbatim} +defines a macro \cs{b} +with one parameter. + +Let us examine the handling of the parameter character +in some detail. +Consider \begin{verbatim} +\def\a#1{ .. #1 .. \def\b##1{ ... }} +\end{verbatim} +When this is read as input, the input processor +\begin{itemize} +\item replaces the characters \verb>#1> by \gr{parameter token$_1$}, and +\item replaces the characters \verb>##> by \verb>#>\end{itemize} +A macro call of \cs{a} will then let the input processor scan +\begin{verbatim} +\def\b#1{ ... } +\end{verbatim} +in which the two characters \verb>#1> are +\alt +replaced by a parameter token. + +%\spoint Brace delimiting +\subsection{Brace delimiting} + +Ordinarily, it is not possible to have left or right +braces in the \gr{parameter text} of a definition. +There is a special mechanism, however, that can make +the last parameter of a macro act as if it is delimited +by an opening brace. + +If the last parameter token +is followed by a parameter character (\verb>#>), +which in turn is followed by the opening brace of the +replacement text, \TeX\ makes the last parameter +be delimited by a beginning-of-group character. +Furthermore, unlike other delimiting tokens in +parameter texts, this opening brace is not +removed from the input stream. + +Consider an example. +Suppose we want to have a macro +\cs{every} that can fill token lists as follows: +\begin{verbatim} +\every par{abc} \every display{def} +\end{verbatim} +This macro can be defined as +\begin{verbatim} +\def\every#1#{\csname every#1\endcsname} +\end{verbatim} +In the first call above, the argument corresponding to +the parameter is \n{abc}, so the call +expands to +\begin{verbatim} +\csname everypar\endcsname{abc} +\end{verbatim} +which gives the desired result. + + +%\point[cs:name] Construction of control sequences +\section{Construction of control sequences} +\label{cs:name} + +The commands \csidx{csname} and \csidx{endcsname} can be used +to construct a control sequence. +For instance \begin{verbatim} +\csname hskip\endcsname 5pt +\end{verbatim} +is equivalent to \verb=\hskip5pt=. + +During this construction process +all macros and other expandable control sequences +between \cs{csname} and \cs{endcsname} +are expanded as usual, until only unexpandable +character tokens remain. A~variation of the above example, +\begin{verbatim} +\csname \ifhmode h\else v\fi skip\endcsname 5pt +\end{verbatim} +performs an \cs{hskip} or \cs{vskip} depending on the mode. +The final result of the expansion should +consist of only character tokens, but +their category codes do not matter. +An unexpandable control sequence gives an error here: +\TeX\ will insert an \cs{endcsname} right before it +as an attempt at error recovery. + +With \cs{csname} it is possible to construct +control sequences that cannot ordinarily be written, +because the constituent character tokens may have another category +\alt +than~11, letter. This principle can be used to hide +\howto Hide counters from the user\par +inner control sequences of a macro package from the user. +\begin{example}\begin{verbatim} +\def\newcounter#1{\expandafter\newcount + \csname #1:counter\endcsname} +\def\stepcounter#1{\expandafter\advance + \csname #1:counter\endcsname 1\relax} +\end{verbatim} +In the second definition the \cs{expandafter} is superfluous, +but it does no harm, and it is conceptually clearer. +\end{example} + +The name of the actual counter created by \cs{newcounter} +contains a colon, so that it takes some effort to write this +control sequence. In effect, the counter +is now hidden from the user, who can only +access it through control sequences such as \cs{stepcounter}. +By the way, the macro \cs{newcount} is defined \cs{outer} in +the plain format, so the above definition of \cs{newcounter} +can only be written after \cs{newcount} has been redefined. + +If a control sequence formed with \verb>\csname...\endcsname> +has not been defined +before, its meaning is set to \cs{relax}. +Thus if \verb=\xx= is an undefined control sequence, the +command \begin{verbatim} +\csname xx\endcsname +\end{verbatim} +will {\em not\/} +give an error message, as it is equivalent to \verb=\relax=. +Moreover, after this execution of the +\verb-\csname...\endcsname- statement, the control sequence +\verb=\xx= is itself equivalent to \cs{relax}, so it +will no longer give an `undefined control sequence' error +(see also page~\pageref{relax:cs}). + + +%\point Token assignments by \cs{let} and \cs{futurelet} +\section{Token assignments by \protect\cs{let} and \protect\cs{futurelet}} + +There are two \gr{let assignment}s in \TeX. +Their syntax is +\begin{disp}\cs{let}\gr{control sequence}\gr{equals}% + \gr{one optional space}\gr{token}\nl + \cs{futurelet}\gr{control sequence}\gr{token}\gr{token} + \end{disp} +In the syntax of a \cs{futurelet} assignment +no optional equals sign appears. + +%\spoint[let] \cs{let} +\subsection{\protect\cs{let}} +\label{let} + +The primitive command \csidx{let} assigns the current meaning +of a~token to a control sequence or active character. + +For instance, in the plain format \cs{endgraf} is defined +as \begin{verbatim} +\let\endgraf=\par +\end{verbatim} +This enables macro writers to redefine \cs{par}, while +still having the functionality of the primitive \cs{par} +command available. For example, +\begin{verbatim} +\everypar={\bgroup\it\def\par{\endgraf\egroup}} +\end{verbatim} + +The case where the \gr{token} to be assigned is not a control +sequence but a character token instead has been treated +in Chapter~\ref{char}. + +%\spoint \cs{futurelet} +\subsection{\protect\cs{futurelet}} + +As was explained above, the sequence with \cs{let} +\begin{disp}\cs{let}\gr{control sequence}\gr{token$_1$}\gr{token$_2$}% + \gr{token$_3$}\gr{token$\cdots$}\end{disp} +assigns (the meaning of) \gr{token$_1$} to the control sequence, +and the remaining input stream looks like +\begin{disp}\gr{token$_2$}\gr{token$_3$}\gr{token$\cdots$}\end{disp} +That is, the \gr{token$_1$} has disappeared from the stream. + +The command \csidx{futurelet} works slightly differently: +given the input stream +\begin{disp}\cs{futurelet}\gr{control sequence}\gr{token$_1$}\gr{token$_2$}% + \gr{token$_3$}\gr{token$\cdots$}\end{disp} +it assigns (the meaning of) \gr{token$_2$} to the control sequence, +and the remaining stream looks like +\begin{disp}\gr{token$_1$}\gr{token$_2$}\gr{token$_3$}\gr{token$\cdots$}\end{disp} +That is, neither \gr{token$_1$} nor \gr{token$_2$} has +been lifted from the stream. +However, now \gr{token$_1$} +`knows' what \gr{token$_2$} is, without having had to absorb it +as a macro parameter. See an example below. + +If a character token has been \cs{futurelet} to a control +sequence, its category code is fixed. +The subsequent \gr{token$_1$} cannot change +it anymore. + +%\point Assorted remarks +\section{Assorted remarks} + +%\spoint Active characters +\subsection{Active characters} + +Character tokens of category~13, `active characters', +\altt +can be defined just like +\term active character\par\term character !active\par +control sequences. +If the definition of the character appears inside a macro, +the character has to be active at the time of the definition +of that macro. + +Consider for example the following definition +(taken from Chapter~\ref{mouth}):\begin{verbatim} +{\catcode`\^^M=13 % + \gdef\obeylines{\catcode`\^^M=13 \def^^M{\par}}% +} +\end{verbatim} +The unusual category of the \verb>^^M> character +has to be set during the definition of \cs{obeylines}, +otherwise \TeX\ would think that the line ended +after \cs{def}. + +%\spoint Macros versus primitives +\subsection{Macros versus primitives} + +The distinction between primitive commands and user macros +\term primitive commands\par\term command !primitive\par +is not nearly as important in \TeX\ as it is in other +programming languages.\begin{itemize} +\item The user can use primitive commands under different names: + \begin{verbatim} +\let\StopThisParagraph=\par +\end{verbatim} +\item Names of primitive commands can be used for + user macros: \begin{verbatim} +\def\par{\hfill$\bullet$\endgraf} +\end{verbatim} +\item Both user macros and a number of \TeX\ primitives + are subject to expansion, for instance all conditionals, + and commands such as \cs{number} and~\cs{jobname}. +\end{itemize} + +%\spoint Tail recursion +\subsection{Tail recursion} + +Macros in \TeX, like procedures in most modern programming +\term recursion\par +languages, are allowed to be recursive: that is, the +definition of a macro can contain a call to this same macro, +or to another macro that will call this macro. +Recursive macros tend to clutter up \TeX's memory +if too many `incarnations' of such a macro are active +at the same time. However, \TeX\ is able to prevent this +in one frequently occurring case of recursion: tail recursion. + +In order to appreciate what goes on here, some background +knowledge is needed. When \TeX\ starts executing a macro +it absorbs the parameters, and places an item pointing to +the replacement text on the input stack, +\term input! stack\par +so that the scanner will next be directed to +this replacement. Once it has been processed, the item on the +input stack can be removed. +However, if the definition text +of a macro contains further macros, this process will be +repeated for them: new items may be placed on the input stack +directing the scanner to other macros +even before the first one has been completed. + +In general this `stack build-up' is a necessary evil, but +it can be prevented if the nested macro call is the +{\em last\/} token in the replacement text of the original +macro. After the last token no further tokens need to be +considered, so one might as well clear the top item +from the input stack +before a new one is put there. +This is what \TeX\ does. + +The \csidx{loop} macro of plain \TeX\ provides a good illustration +\label{loop:ex} +of this principle. The definition is +\begin{verbatim} +\def\loop#1\repeat{\def\body{#1}\iterate} +\def\iterate{\body \let\next=\iterate + \else \let\next=\relax\fi \next} +\end{verbatim} +and this macro can be called for example as follows: +\begin{verbatim} +\loop \message{\number\MyCount} + \advance\MyCount by 1 + \ifnum\MyCount<100 \repeat +\end{verbatim} +The macro \cs{iterate} can call itself and, when it does so, +the recursive call is performed by the last token in the list. +It would have been possible to define \cs{iterate} +as \begin{verbatim} +\def\iterate{\body \iterate\fi} +\end{verbatim} +but then \TeX\ would not have been able to resolve the recursion +as the call \cs{iterate} is not the last token in the replacement +text of \cs{iterate}. Assigning \verb>\let\next=\iterate> +is here a way to let +the recursive call be the last token in the list. + +Another way of resolving tail recursion is to use +\cs{expandafter} (see page~\pageref{after:cond}): in +\begin{verbatim} +\def\iterate{\body \expandafter\iterate\fi} +\end{verbatim} +it removes the \cs{fi} token. +Tail recursion would also be resolved if the last +tokens in the list were arguments for the +recursive macro. + +An aside: by defining \cs{iterate} as +\begin{verbatim} +\def\iterate{\let\next\relax + \body \let\next\iterate \fi \next} +\end{verbatim} +it becomes possible to write +\begin{verbatim} +\loop ... \if... ... \else ... \repeat +\end{verbatim} + +%\point Macro techniques +\section{Macro techniques} + +%\spoint Unknown number of arguments +\subsection{Unknown number of arguments} + +In some applications, +\howto Macros with an undetermined number +of arguments\par +a macro is needed that can have a +number of arguments that is not specified in advance. + +Consider the problem of translating a position on a chess board +(for full macros and fonts, see~\cite{chess} and~\cite{Tut}), +given like +\begin{verbatim} +\White(Ke1,Qd1,Na1,e2,f4) +\end{verbatim} +to a sequence of typesetting instructions +\begin{verbatim} +\WhitePiece{K}{e1} \WhitePiece{Q}{d1} \WhitePiece{N}{a1} +\WhitePiece{P}{e2} \WhitePiece{P}{f4} +\end{verbatim} +Note that for pawns the `P' is omitted in the list of positions. + +The first problem is that the list of pieces +is of variable length, so we append a terminator piece: +\begin{verbatim} +\def\White(#1){\xWhite#1,xxx,} +\def\endpiece{xxx} +\end{verbatim} +for which we can test. +Next, the macro \cs{xWhite} takes one position from the list, +tests whether it is the terminator, and if not, +subjects it to a test to see whether it is a pawn. +\begin{verbatim} +\def\xWhite#1,{\def\temp{#1}% + \ifx\temp\endpiece + \else \WhitePieceOrPawn#1XY% + \expandafter\xWhite + \fi} +\end{verbatim} +An \cs{expandafter} command is necessary to remove the +\cs{fi} (see page~\pageref{after:cond}), so that +\cs{xWhite} will get the next position as argument +instead of \cs{fi}. + +Positions are either two or three characters long. +The call to \cs{White\-Piece\-OrPawn}, a four-parameter macro, +appended a terminator string \n{XY}. +In the case of a pawn, therefore, argument~3 is the character~\n X +and argument~4 is empty; for all other pieces argument~1 +is the piece, 2~and~3 are the position, and argument~4 is~\n X. +\begin{verbatim} +\def\WhitePieceOrPawn#1#2#3#4Y{ + \if#3X \WhitePiece{P}{#1#2}% + \else \WhitePiece{#1}{#2#3}\fi} +\end{verbatim} + +%\spoint Examining the argument +\subsection{Examining the argument} + +It may be necessary in some cases to test whether a macro +\howto Examine a macro argument for the presence of some element\par +\howto Apply \cs{uppercase} when the argument has a \cs{footnote}\par +argument contains some element. For a real-life example, +consider the following (see also the \cs{DisplayEquation} +\alt +example on page~\pageref{left:display}). + +Suppose the title and author of an article are given as +\begin{verbatim} +\title{An angle trisector} +\author{A.B. Cee\footnote*{Research supported by the +Very Big Company of America}} +\end{verbatim} +with multiple authors +given as +\begin{verbatim} +\author{A.B. Cee\footnote*{Supported by NSF grant 1} + \and + X.Y. Zee\footnote{**}{Supported by NATO grant 2}} +\end{verbatim} +Suppose further that the \cs{title} and \cs{author} macros +are defined as +\begin{verbatim} +\def\title#1{\def\TheTitle{#1}} \def\author#1{\def\TheAuthor{#1}} +\end{verbatim} +which will be used as +\begin{verbatim} +\def\ArticleHeading{ ... \TheTitle ... \TheAuthor ... } +\end{verbatim} + +For some journals it is required to +have the authorship and the title of the article in all capitals. +The implementation of this could be +\begin{verbatim} +\def\ArticleCapitalHeading + { ... + \uppercase\expandafter{\TheTitle} + ... + \uppercase\expandafter{\TheAuthor} + ... + } +\end{verbatim} +Now the \cs{expandafter} commands will expand the title and +author into the actual texts, and the \cs{uppercase} commands +will capitalize them. However, for the authors this is wrong, +since the \cs{uppercase} command will also capitalize the +footnote texts. +The problem is then to uppercase only the parts +of the title in between the footnotes. + +As a first attempt, let us take the case of one author, and +let the basic call be +\begin{verbatim} +\expandafter\UCnoFootnote\TheAuthor +\end{verbatim} +This expands into +\begin{verbatim} +\UCnoFootnote A.B. Cee\footnote*{Supported ... } +\end{verbatim} +The macro +\begin{verbatim} +\def\UCnoFootnote#1\footnote#2#3{\uppercase{#1}\footnote{#2}{#3}} +\end{verbatim} +will analyse this correctly: +\begin{verbatim} +#1<-A.B. Cee +#2<-* +#3<-Supported ... +\end{verbatim} +However, if there is no footnote, this macro is completely wrong. + +As a first refinement we add a footnote ourselves, just to make +sure that one is present: +\begin{verbatim} +\expandafter\UCnoFootnote\TheAuthor\footnote 00 +\end{verbatim} +Now we have to test what kind of footnote we find: +\begin{verbatim} +\def\stopper{0} +\def\UCnoFootnote#1\footnote#2#3{\uppercase{#1}\def\tester{#2}% + \ifx\stopper\tester + \else\footnote{#2}{#3}\fi} +\end{verbatim} +With \cs{ifx} we test the delimiter footnote sign against the +actual sign encountered. Note that a solution with +\begin{verbatim} +\ifx0#2 +\end{verbatim} +would be wrong if the footnote sign consists +of more than one token, for instance~\verb>{**}>. + +The macro so far is correct if there was no footnote, +but if there was one it is wrong: +the terminating tokens remain to be disposed of. +They are taken care of in the following version: +\begin{verbatim} +\def\stopper{0} +\def\UCnoFootnote#1\footnote#2#3{\uppercase{#1}\def\tester{#2}% + \ifx\stopper\tester + \else\footnote{#2}{#3}\expandafter\UCnoFootnote + \fi} +\end{verbatim} +A repeated call to \cs{UCnoFootnote} removes the delimiter tokens +(the \cs{expandafter} first removes the \cs{fi}), +and as an added bonus, this macro is also correct for multiple +authors. + + +%\spoint Optional macro parameters with \cs{futurelet} +\subsection{Optional macro parameters with \protect\cs{futurelet}} + +One standard application of \cs{futurelet} is implementing +\howto Macros with optional parameters\par +optional parameters of macros. The general course of action +is as follows: +\begin{verbatim} +\def\Com{\futurelet\testchar\MaybeOptArgCom} +\def\MaybeOptArgCom{\ifx[\testchar \let\next\OptArgCom + \else \let\next\NoOptArgCom \fi \next} +\def\OptArgCom[#1]#2{ ... }\def\NoOptArgCom#1{ ... } +\end{verbatim} +Note that \cs{ifx} is used even though it tests +for a character. The reason is of course that, +if the optional argument is omitted, there might be an +expandable control sequence behind the~\cs{Com}. + +The macro \cs{Com} now has one optional and one regular +argument; it can be called as +\begin{verbatim} +\Com{argument} +\end{verbatim} +or as\begin{verbatim} +\Com[optional]{argument} +\end{verbatim} +Often the call without the optional argument will insert some +default value: +\begin{disp}\verb>\def\NoOptArgCom#1{\OptArgCom[>% +{\italic default\/}\verb>]{#1}}>\end{disp} +This mechanism is widely used in formats such as \LaTeX\ and +\LamsTeX; see also~\cite{svb:future}. + + + +%\spoint Two-step macros +\subsection{Two-step macros} + +Often what looks to the user like one macro is in reality +a two-step process, where one macro will set up conditions, +and a second macro will do the work. + +As an example, here is +a macro \cs{PickToEol}\label{pick:eol} +\howto Take an input line as macro argument\par +with an argument that is delimited by the line end. +First we write a macro without arguments that +changes the category code of the line end, and then +calls the second macro. +\begin{verbatim} +\def\PickToEol{\begingroup\catcode`\^^M=12 \xPickToEol} +\end{verbatim} +The second macro can then take as an argument everything +up to the end of the line: +\begin{verbatim} +\def\xPickToEol#1^^M{ ... #1 ... \endgroup} +\end{verbatim} +There is one problem with this definition: the \verb>^^M> character +should have category~12. We arrive at the following: +\begin{verbatim} +\def\PickToEol{\begingroup\catcode`\^^M=12 \xPickToEol} +{\catcode`\^^M=12 % + \gdef\xPickToEol#1^^M{ ... #1 ... \endgroup}% +} +\end{verbatim} +where the category code of \verb>^^M> is changed for the +sake of the definition of \cs{xPickToEol}. Note that +the \verb>^^M> in \cs{PickToEol} occurs in a control symbol, +so there the category code is irrelevant. Therefore that +definition can be outside the group where the category code +of \verb>^^M> is redefined. + + +%\spoint A comment environment +\subsection{ A comment environment} + +As an application of the above idea of two-step macros, +\howto Comment environment\par +and in order to illustrate tail recursion, here are +macros for a `comment' environment. + +Often it is necessary to remove a part of \TeX\ +input temporarily. For this one would like to +write \begin{verbatim} +\comment +... +\endcomment +\end{verbatim} +The simplest implementation of this, +\begin{verbatim} +\def\comment#1\endcomment{} +\end{verbatim} +has a number of weaknesses. For instance, +it cannot cope with outer macros or input that +does not have balanced braces. Its worst +shortcoming, however, is that it reads the complete +comment text as a macro argument. This limits the size +of the comment to that of \TeX's input buffer. + +It would be a better idea to take on the out-commented +text one line at a time. For this we want to write +a recursive macro with a basic structure +\begin{verbatim} +\def\comment#1^^M{ ... \comment } +\end{verbatim} +In order to be able to write this definition at all, +the category code of the line end must be changed; as above +\altt +we will have +\begin{verbatim} +\def\comment{\begingroup \catcode`\^^M=12 \xcomment} +{\catcode`\^^M=12 \endlinechar=-1 % + \gdef\xcomment#1^^M{ ... \xcomment} +} +\end{verbatim} +Changing the \cs{endlinechar} is merely to +prevent having to put comment characters at the end +of every line of the definition. + +Of course, the process must stop at a certain time. +To this purpose we investigate the line that was +scooped up as macro argument: +\begin{verbatim} +{\catcode`\^^M=12 \endlinechar=-1 % + \gdef\xcomment#1^^M{\def\test{#1} + \ifx\test\endcomment \let\next=\endgroup + \else \let\next=\xcomment \fi + \next} +} +\end{verbatim} +and we have to define \cs{endcomment}: +\begin{verbatim} +\def\endcomment{\endcomment} +\end{verbatim} +This command will never be executed: it is merely for purposes +of testing whether the end of the environment has been reached. + +We may want to comment out text that is not syntactically +correct. Therefore we switch to a verbatim mode +\term verbatim mode\par +when commenting. The following macro is given +in plain \TeX: +\begin{verbatim} +\def\dospecials{\do\ \do\\\do\{\do\}\do\$\do\&% + \do\#\do\^\do\^^K\do\_\do\^^A\do\%\do\~} +\end{verbatim} +We use it to define \cs{comment} as follows: +\begin{verbatim} +\def\makeinnocent#1{\catcode`#1=12 } +\def\comment{\begingroup + \let\do=\makeinnocent \dospecials + \endlinechar`\^^M \catcode`\^^M=12 \xcomment} +\end{verbatim} +Apart from the possibility mentioned above of commenting +out text that is not syntactically correct, for instance +because of unmatched braces, this solution can handle +outer macros. The former implementation of \cs{xcomment} +would cause a \TeX\ error if one occurred in the comment text. + +However, using verbatim mode poses the problem of concluding the +environment. +\altt +The final line of the comment is now not the control sequence +\cs{endcomment}, but the characters constituting it. We have +to test for these then: +\begin{verbatim} +{\escapechar=-1 + \xdef\endcomment{\string\\endcomment} +} +\end{verbatim} +The sequence \verb>\string\\> gives a backslash. +We could not have used +\begin{verbatim} +\edef\endcomment{\string\endcomment} +\end{verbatim} +because +the letters of the word \n{endcomment} would then have +category code~12, instead of the 11 that the ones on the +last line of the comment will have. + +%%%% end of input file [macro] + +%\InputFile:expand +%%%% this is input file [expand] +%\subject[expand] Expansion +\endofchapter +\chapter{Expansion}\label{expand} + +Expansion in \TeX\ is rather different from procedure calls +\term expansion\par +in most programming languages. This chapter treats the +commands connected with expansion, and gives a number of +(non-trivial) examples. + +\begin{inventory} +\item [\cs{relax}] + Do nothing. + + +\item [\cs{expandafter}] + Take the next two tokens and place the expansion of the + second after the first. + +\item [\cs{noexpand}] + Do not expand the next token. + + +\item [\cs{edef}] + Start a macro definition; + the replacement text is expanded at definition time. + + +\item [\cs{aftergroup}] + Save the next token for insertion after the current group. + +\item [\cs{afterassignment}] + Save the next token for execution after the next assignment + or macro definition. + + +\item [\cs{the}] + Expand the value of various quantities in \TeX\ into a string + of character tokens. + +\end{inventory} + + +%\point Introduction +\section{Introduction} + +\TeX's expansion processor accepts a stream of tokens +coming out of the input processor, and its result is +again a stream of tokens, which it feeds to the execution +processor. For the input processor there are two +kinds of tokens: expandable and unexpandable ones. +The latter category is passed untouched, and it contains +largely assignments and typesettable material; +the former category +is expanded, and the result of that expansion is examined anew. + +%\point Ordinary expansion +\section{Ordinary expansion} + +The following list gives those constructs +that are expanded, unless +expansion is inhibited: +\begin{itemize} +\item macros\label{expand:lijst} +\term expansion!expandable control sequences\par +\item conditionals +\item \cs{number}, \cs{romannumeral} +\item \cs{string}, \cs{fontname}, \cs{jobname}, + \cs{meaning}, \cs{the} +\item \verb,\csname ... \endcsname, +\item \cs{expandafter}, \cs{noexpand} +\item \cs{topmark}, \cs{botmark}, \cs{firstmark}, + \cs{splitfirstmark}, \cs{splitbotmark} +\item \cs{input}, \cs{endinput} +\end{itemize} + +This is the list of all instances where +expansion is inhibited: +\begin{itemize}\label{noexp:list} +\item when \TeX\ is reading a token to be defined by + \begin{itemize} \item a \gr{let assignment}, that is, + by \cs{let} or \cs{futurelet}, + \item a \gr{shorthand definition}, that is, + by \cs{chardef} or \cs{mathchardef}, or a + \gr{register def}, that is, \cs{countdef}, + \cs{dimendef}, \cs{skipdef}, \cs{muskipdef}, + or~\cs{toksdef}, + \item a \gr{definition}, that is a macro definition + with \cs{def}, \cs{gdef}, \cs{edef}, or~\cs{xdef}, + \item the \gr{simple assignment}s \cs{read} and \cs{font}; + \end{itemize} +\item when a \gr{parameter text} or macro arguments + are being read; also when the replacement text of a + control sequence + being defined by \cs{def}, \cs{gdef}, or \cs{read} + is being read; +\item when the token list for a \gr{token variable} or + \cs{uppercase}, \cs{lowercase}, or \cs{write} + is being read; however, the token list for \cs{write} + will be expanded later when it is shipped out; +\item when tokens are being deleted during error recovery; +\item when part of a conditional is being skipped; +\item in two instances when \TeX\ has to know what follows + \begin{itemize}\item after a left quote in a context where + that is used to denote an integer (thus in + \verb-\catcode`\a- the \cs{a} is not expanded), or + \item after a math shift character that begins math mode + to see whether another math shift character follows (in which case + a display opens); + \end{itemize} +\item when an alignment preamble is being scanned; however, + in this case a~token + preceded by \cs{span} and the tokens in a \cs{tabskip} + assignment are still expanded. +\end{itemize} + +%\point Reversing expansion order +\section{Reversing expansion order} + +Every once in a while you need to change the normal order of +expansion of tokens. \TeX\ provides several mechanisms for +this. Some of the control sequences in this section are +not strictly concerned with expansion. + +%\spoint One step expansion: \cs{expandafter} +\subsection{One step expansion: \protect\cs{expandafter}} + +The most obvious tool for reversed expansion order is +\csidx{expandafter}. The sequence +\begin{disp}\cs{expandafter}\gr{token$_1$}\gr{token$_2$}\end{disp} +expands to \begin{disp}\gr{token$_1$}\gr{\italic the expansion of token$_2$} +\end{disp} +Note the following. +\begin{itemize} \item If \gr{token$_2$} is a macro, it is replaced +by its replacement text, not by its final expansion. +Thus, if +\begin{verbatim} +\def\tokentwo{\ifsomecondition this \else that \fi} +\def\tokenone#1{ ... } +\end{verbatim} +the call \begin{verbatim} +\expandafter\tokenone\tokentwo +\end{verbatim} +will give \cs{ifsomecondition} as the parameter +to \cs{tokenone}: +\begin{verbatim} +\tokenone #1-> ... +#1<-\ifsomecondition +\end{verbatim} +\item If the \cs{tokentwo} is a macro with one or more +parameters, sufficiently many subsequent tokens will be absorbed +to form the replacement text.\end{itemize} + +%\spoint[expand:edef] Total expansion: \cs{edef} +\subsection{Total expansion: \protect\cs{edef}} +\label{expand:edef} + +Macros are usually defined by \cs{def}, but for the cases where +one wants the replacement text to reflect current conditions +(as opposed to conditions at the time of the call), +there is an `expanding define', \csidx{edef}, which expands +everything in the replacement text, before assigning it to the +control sequence. + +\begin{example}\begin{verbatim} +\edef\modedef{This macro was defined in + `\ifvmode vertical\else \ifmmode math + \else horizontal\fi\fi' mode} +\end{verbatim} +The mode tests will be executed at definition time, so the +replacement text will be a single string. + +As a more useful example, suppose that in a file that will be +\cs{input} the category code of the~\n@ will be changed. +One could then write +\begin{verbatim} +\edef\restorecat{\catcode`@=\the\catcode`@} +\end{verbatim} +at the start, and +\begin{verbatim} +\restorecat +\end{verbatim} +at the end. See page~\pageref{store:cat} +for a fully worked-out version of this. +\end{example} + +Contrary to the `one step expansion' of +\cs{expandafter}, the expansion inside an \cs{edef} is complete: +it goes on +until only unexpandable character and control sequence +tokens remain. +There are two exceptions to this total expansion: +\begin{itemize} \item any control sequence preceded by \cs{noexpand} +is not expanded, and, +\item if \cs{sometokenlist} is a token list, the expression +\begin{verbatim} +\the\sometokenlist +\end{verbatim} +is expanded to the contents +of the list, but the contents are not expanded +any further (see Chapter~\ref{token} for examples).\end{itemize} + +On certain occasions the \cs{edef} can conveniently be +abused, in the sense that one is not interested in defining +a control sequence, but only in the result of the expansion. +For example, with the definitions +\alt +\begin{verbatim} +\def\othermacro{\ifnum1>0 {this}\else {that}\fi} +\def\somemacro#1{ ... } +\end{verbatim} +the call\begin{verbatim} +\expandafter\somemacro\othermacro +\end{verbatim} +gives the parameter assignment +\begin{verbatim} +#1<-\ifnum +\end{verbatim} +This can be repaired by calling +\begin{verbatim} +\edef\next{\noexpand\somemacro\othermacro}\next +\end{verbatim} +Conditionals are completely expanded inside an \cs{edef}, +so the replacement text of \cs{next} will consist of the sequence +\begin{verbatim} +\somemacro{this} +\end{verbatim} +and a~subsequent call to \cs{next} executes this statement. + + +%\spoint \cs{afterassignment} +\subsection{\protect\cs{afterassignment}} +\label{sec:afterassignment} + +The \cstoidx afterassignment\par\ command +takes one token and sets it aside for insertion +in the token stream +after the next assignment or macro definition. +If the first assignment is of a~box + to a box register, +the token will be inserted right after the opening +\alt +brace of the box (see page~\pageref{every:box:assign}). + +Only one token can be saved this way; a subsequent token +saved by \cs{afterassignment} will override the first. + +Let us consider an example of the use of \cs{afterassignment}. +It is often desirable to have a macro that will +\begin{itemize} \item assign the argument to some variable, and then +\item do a little calculation, based on the new value +of the variable.\end{itemize} +The following example illustrates the +straightforward approach: +\begin{verbatim} +\def\setfontsize#1{\thefontsize=#1pt\relax + \baselineskip=1.2\thefontsize\relax} +\setfontsize{10} +\end{verbatim} +A more elegant solution is possible using \cs{afterassignment}: +\begin{verbatim} +\def\setbaselineskip + {\baselineskip=1.2\thefontsize\relax} +\def\fontsize{\afterassignment\setbaselineskip + \thefontsize} +\fontsize=10pt +\end{verbatim} +Now the macro looks like an assignment: the equals sign +is even optional. In reality its expansion +ends with a variable to be assigned to. The control sequence +\cs{setbaselineskip} is saved for execution after +the assignment to \cs{thefontsize}. + +Examples of \cs{afterassignment} in plain \TeX\ are +the \cs{magnification} and \cs{hglue} macros. +See \cite{Maus} for another creative application of +this command. + +%\spoint \cs{aftergroup} +\subsection{\protect\cs{aftergroup}} + +Several tokens can be saved for insertion after the current +\cstoidx aftergroup\par +group with an \begin{disp}\cs{aftergroup}\gr{token}\end{disp} command. +The tokens are inserted after the group in the sequence +the \cs{aftergroup} commands were given in. +The group can be delimited either by implicit or explicit +braces, or by \cs{begingroup} and \cs{endgroup}. + +\begin{example}\begin{verbatim} +{\aftergroup\a \aftergroup\b} +\end{verbatim} +is equivalent to \begin{verbatim} +\a \b +\end{verbatim} +\end{example} + +This command has many applications. One can be found +\alt +in the \cs{textvcenter} macro on page~\pageref{text:vcenter}; +another one is provided +by the footnote mechanism of plain \TeX. + +The footnote command of plain \TeX\ has the layout +\label{footnote:ex} +\begin{disp}\cs{footnote}\gr{footnote symbol}\lb\gr{footnote text}\rb +\end{disp} which looks like a macro with two arguments. +However, it is undesirable to scoop up the footnote text, +since this precludes for +instance category code changes in the footnote. + +What happens in the plain footnote macro is (globally) the following. +\begin{itemize}\item The \cs{footnote} command opens +an insert, \begin{verbatim} +\def\footnote#1{ ...#1... %treat the footnote sign + \insert\footins\bgroup +\end{verbatim} +\item In the insert box a group is opened, +and an \cs{aftergroup} command +is given to close off the insert properly: +\begin{verbatim} + \bgroup\aftergroup\@foot +\end{verbatim} +This command is meant to wind up after the closing brace of +the text that the user typed to end the footnote text; +the opening brace of the user's footnote text must +be removed by +\begin{verbatim} + \let\next=}%end of definition \footnote +\end{verbatim} +which assigns the next token, the brace, to \cs{next}. +\item The footnote text is set as ordinary text +in this insert box. +\item After the footnote the command \cs{@foot} +defined by \begin{verbatim} +\def\@foot{\strut\egroup} +\end{verbatim} +will be executed.\end{itemize} + + +%\point Preventing expansion +\section{Preventing expansion} + +Sometimes it is necessary to prevent expansion in a place +where it normally occurs. For this purpose the control +sequences \csidx{string} and \csidx{noexpand} are available. + +The use of \cs{string} is rather limited, since it converts +a control sequence token into a string of characters, with +the value of \cs{escapechar} used for the character of +category code~0. It is eminently suitable for use in a +\cs{write}, in order to output a control sequence name +(see also Chapter~\ref{io}); for another application see +the explanation of \cs{newif} in Chapter~\ref{if}. + +All characters resulting from \cs{string} have category +code~12, `other', except for space characters; they receive +code~10. See also Chapter~\ref{char}. + +%\spoint \cs{noexpand} +\subsection{\protect\cs{noexpand}} + +The \cs{noexpand} command is expandable, and its expansion +is the following token. The meaning of that token is +made temporarily equal to \cs{relax}, so that it cannot +be expanded further. + +For \cs{noexpand} the most important application is probably +in \cs{edef} commands (but in write statements it can often +replace \cs{string}). Consider as an example +\begin{verbatim} + \edef\one{\def\noexpand\two{\the\prevdepth}} +\end{verbatim} +Without the \cs{noexpand}, \TeX\ would try to expand +\cs{two}, thus giving an `undefined control sequence' error. + +A (rather pointless) +illustration of the fact that \cs{noexpand} makes the following +token effectively into a \cs{relax} is +\begin{verbatim} +\def\a{b} +\noexpand\a +\end{verbatim} +This will not produce any output, because the +effect of the \cs{noexpand} is to make the control sequence +\cs{a} temporarily equal to \cs{relax}. + +%\spoint \cs{noexpand} and active characters +\subsection{\protect\cs{noexpand} and active characters} + +The combination \cs{noexpand}\gr{token} is +\term character !active, and \cs{noexpand}\par +equivalent to \cs{relax}, even if the token +is an active character. Thus, +\begin{verbatim} +\csname\noexpand~\endcsname +\end{verbatim} +will not be the same as~\verb>\char`\~>. +Instead it will give an error message, because +unexpandable commands \ldash such as \cs{relax} \rdash are not allowed to appear +in between \cs{csname} and \cs{endcsname}. +The solution is to use \cs{string} instead; see page~\pageref{store:cat} +for an example. + +In another context, however, the sequence +\cs{noexpand}\gr{active character} is equivalent +to the character, but in unexpandable form. This is +when the conditionals \cs{if} and \cs{ifcat} are used +(for an explanation of these, see Chapter~\ref{if}). +Compare +\begin{verbatim} +\if\noexpand~\relax % is false +\end{verbatim} +where the character code of the tilde is tested, with +\begin{verbatim} +\def\a{ ... } \if\noexpand\a\relax % is true +\end{verbatim} +where two control sequences are tested. + +%\point \cs{relax} +\section{\protect\cs{relax}} + +The control sequence \csidx{relax} cannot be expanded, but +when it is executed nothing happens. + +This statement sounds a bit paradoxical, so consider +an example. Let counters \begin{verbatim} +\newcount\MyCount +\newcount\MyOtherCount \MyOtherCount=2 +\end{verbatim} +be given. +In the assignment \begin{verbatim} +\MyCount=1\number\MyOtherCount3\relax4 +\end{verbatim} +the command \cs{number} is expandable, and \cs{relax} is not. +When \TeX\ constructs the number that is to be assigned +it will expand all commands, either until a non-digit is +found, or until an unexpandable command is encountered. +Thus it reads the~\n1; it expands the sequence \verb>\number\MyOtherCount>, +which gives~\n2; it reads the~\n3; it sees the \cs{relax}, and +as this is unexpandable it halts. The number to be assigned +is then \n{123}, and the whole call has been expanded into +\begin{verbatim} +\MyCount=123\relax4 +\end{verbatim} +Since the \cs{relax} token has no effect when it is executed, +the result of this line is that \n{123} is assigned to +\cs{MyCount}, and the digit 4 is printed. + +Another example of how \cs{relax} can be used to indicate +the end of a command\label{fil:l:l}\ is +\begin{verbatim} +\everypar{\hskip 0cm plus 1fil } +\indent Later that day, ... +\end{verbatim} +This will be misunderstood: \TeX\ will see +\begin{verbatim} +\hskip 0cm plus 1fil L +\end{verbatim} +and \hbox{\n{fil L}} is a~valid, +if bizarre, +way of writing \n{fill} (see Chapter~\ref{gramm}). +One remedy is to write +\begin{verbatim} +\everypar{\hskip 0cm plus 1fil\relax} +\end{verbatim} + +%\spoint[relax:cs] \cs{relax} and \cs{csname} +\subsection{\cs{relax} and \cs{csname}} +\label{relax:cs} + +If a \verb-\csname ... \endcsname- command forms the name +of a previously undefined control sequence, +that control sequence is made equal to \cs{relax}, +and the whole statement is also equivalent to \cs{relax} +(see also page~\pageref{cs:name}). + +However, this assignment of \cs{relax} is +\altt +only local: +\begin{verbatim} +{\xdef\test{\expandafter\noexpand\csname xx\endcsname}} +\test +\end{verbatim} +gives an error message for an +undefined control sequence~\cs{xx}. + +Consider as an example the \LaTeX\ environments, +which are delimited by \begin{verbatim} +\begin{...} ... \end{...} +\end{verbatim} +The begin and end commands are (in essence) +defined as follows: +\begin{verbatim} +\def\begin#1{\begingroup\csname#1\endcsname} +\def\end#1{\csname end#1\endcsname \endgroup} +\end{verbatim} +Thus, for the list environment the commands +\cs{list} and \cs{endlist} are defined, but any +command can be used as an environment name, +even if no corresponding \cs{end...} has been defined. +For instance, \begin{verbatim} +\begin{it} ... \end{it} +\end{verbatim} +is equivalent to +\begin{verbatim} +\begingroup\it ... \relax\endgroup +\end{verbatim} +See page~\pageref{begin:end:macros} for the rationale +behind using \cs{begingroup} and \cs{endgroup} +instead of \cs{bgroup} and \cs{egroup}. + +%\spoint Preventing expansion with \cs{relax} +\subsection{Preventing expansion with \cs{relax}} + +Because \cs{relax} +cannot be expanded, a control sequence can be prevented +from being expanded (for instance in an \cs{edef} or a \cs{write}) +by making it temporarily equal to \cs{relax}: +\begin{verbatim} +{\let\somemacro=\relax \write\outfile{\somemacro}} +\end{verbatim} +will write the string `\cs{somemacro}' to an output file. +It would write the expansion +of the macro \cs{somemacro} (or give an error message +if the macro is undefined) if the \cs{let} statement +had been omitted. + +%\spoint[bump:relax] \TeX\ inserts a \cs{relax} +\subsection{\TeX\ inserts a \cs{relax}} +\label{bump:relax} + +\TeX\ itself inserts \cs{relax} on some occasions. +For instance, \cs{relax} is inserted if \TeX\ encounters an +\cs{or}, \cs{else}, or~\cs{fi} while still determining +the extent of the test. +\begin{example} +\begin{verbatim} +\ifvoid1\else ... \fi +\end{verbatim} +is changed into +\begin{verbatim} +\ifvoid1\relax \else ...\fi +\end{verbatim} +internally. +\end{example} + +Similarly, if one of the tests \cs{if}, \cs{ifcat} +is given only one comparand, as in \begin{verbatim} +\if1\else ... +\end{verbatim} +a \cs{relax} token is inserted. Thus this test +is equivalent to \begin{verbatim} +\if1\relax\else ... +\end{verbatim} + +Another place where \cs{relax} is used is the following. +While a control sequence is being defined in a \gr{shorthand +definition} \ldash that is, a \gr{registerdef} or \cs{chardef} +or \cs{mathchardef} \rdash its meaning is temporarily made +equal to \cs{relax}. This makes it possible to write +\verb>\chardef\foo=123\foo>. + +%\spoint The value of non-macros; \cs{the} +\subsection{The value of non-macros; \cs{the}} + +Expansion is a precisely defined activity in \TeX. +\cstoidx the\par +The full list of tokens that can be expanded +was given above. +Other tokens than those in the above list may have an `expansion' +in an informal sense. For instance one may wish to `expand' +the \cs{parindent} into its value, say~\n{20pt}. + +Converting the value of (among others) an +\gr{integer parameter}, a \gr{glue parameter}, +\gr{dimen parameter} or a \gr{token parameter} +into a string of character tokens is done by the expansion processor. +The command \cs{the} +is expanded whenever expansion is not inhibited, +and it takes the value of various sorts of parameters. +Its result (in most cases) +is a string of tokens of category~12, except +that spaces have category code~10. + +Here is the list of everything that can be prefixed with \cs{the}. +\begin{description}\item [\gr{parameter} or \gr{register}] +If the parameter or register is of type integer, glue, dimen +or muglue, +its value is given as a string of character tokens; +if it is of type token list (for instance +\cs{everypar} or \cs{toks5}), the result is a string of tokens. +Box registers are excluded here. +\item [\gr{codename}\gr{8-bit number}] +See page~\pageref{codename}. +\item [\gr{special register}] +The integer registers \cs{prevgraf}, \cs{deadcycles}, \cs{insertpenalties} +\cs{inputlineno}, \cs{badness}, \cs{parshape}, \cs{spacefactor} +(only in horizontal mode), or \cs{prevdepth} (only in vertical mode). +The dimension registers \cs{pagetotal}, \cs{pagegoal}, \cs{pagestretch}, +\cs{pagefilstretch}, \cs{pagefillstretch}, \cs{pagefilllstretch}, +\cs{pageshrink}, or \cs{pagedepth}. +\item [Font properties:] +\cs{fontdimen}\gr{parameter number}\gr{font}, +\cs{skew\-char}\gr{font}, +\cs{hy\-phen\-char}\gr{font}. +\item [Last quantities:] +\cs{lastpenalty}, \cs{lastkern}, \cs{lastskip}. +\item [\gr{defined character}] +Any control sequence defined by \cs{chardef} or \cs{mathchardef}; +the result is the decimal value. +\end{description} +In some cases \cs{the} can give a control sequence token +or list of such tokens. +\begin{description}\item [\gr{font}] +The result is the control sequence that stands for the +font. +\item [\gr{token variable}] +Token list registers and \gr{token parameter}s can be prefixed +with \cs{the}; the result is their contents. +\end{description} + +Let us consider an example of the use of \cs{the}. +If in a file that is to be \cs{input} the +category code of a character, say the at~sign, is changed, +one could write +\begin{verbatim} +\edef\restorecat{\catcode`@=\the\catcode`@} +\end{verbatim} +and call \cs{restorecat} at the end of the file. +If the category code was~11, \cs{restorecat} +is defined equivalent to \begin{verbatim} +\catcode`@=11 +\end{verbatim} +See page~\pageref{store:cat} for more elaborate macros +for saving and restoring catcodes. + + +%\point Examples +\section{Examples} + +%\spoint Expanding after +\subsection{Expanding after} + +The most obvious use of \cs{expandafter} is to reach over +a control sequence: +\begin{verbatim} +\def\stepcounter + #1{\expandafter\advance\csname + #1:counter\endcsname 1\relax} +\stepcounter{foo} +\end{verbatim} +Here the \cs{expandafter} lets the \cs{csname} command form +the control sequence \cs{foo:counter}; after \cs{expandafter} +is finished the statement has reduced to +\begin{verbatim} +\advance\foo:counter 1\relax +\end{verbatim} +It is possible to reach over tokens other than control sequences: in +\begin{verbatim} +\uppercase\expandafter{\romannumeral \year} +\end{verbatim} +it expands \cs{romannumeral} on the other side of the opening +brace. + +You can expand after two control sequences: +\begin{verbatim} +\def\globalstepcounter + #1{\expandafter\global\expandafter\advance + \csname #1:counter\endcsname 1\relax} +\end{verbatim} +If you think of \cs{expandafter} as reversing the evaluation +order of {\sl two\/} control sequences, you can reverse +{\sl three\/} by +\begin{verbatim} +\expandafter\expandafter\expandafter\a\expandafter\b\c +\end{verbatim} +which reaches across the three control sequences +\begin{verbatim} + \expandafter \a \b +\end{verbatim} +to expand \cs{c} first. + +There is even an unexpected use for \cs{expandafter} in +conditionals; +with \begin{verbatim} +\def\bold#1{{\bf #1}} +\end{verbatim} +the sequence \begin{verbatim} +\ifnum1>0 \bold \fi {word} +\end{verbatim} +will not give a boldface `word', but +\begin{verbatim} +\ifnum1>0 \expandafter\bold \fi {word} +\end{verbatim} +will. +The \cs{expandafter} lets \TeX\ see the \cs{fi} and remove it +before it tackles the macro \cs{bold} +(see also page~\pageref{after:cond}). + +%\spoint Defining inside an \cs{edef} +\subsection{Defining inside an \cs{edef}} + +There is one \TeX\ command that is executed instead of +expanded that is worth pointing out explicitly: +the primitive command \cs{def} (and all other \gr{def} commands) +is not expanded. + +Thus the call +\begin{verbatim} +\edef\next{\def\thing{text}} +\end{verbatim} +will give an `undefined +control sequence' for \cs{thing}, even though after +\cs{def} expansion is ordinarily inhibited (see page~\pageref{noexp:list}). +After \begin{verbatim} +\edef\next{\def\noexpand\thing{text}} +\end{verbatim} +the `meaning' of \cs{next} will be \begin{verbatim} +macro: \def \thing {text} +\end{verbatim} +The definition \begin{verbatim} +\edef\next{\def\noexpand\thing{text}\thing} +\end{verbatim} +will again give an `undefined control sequence' for \cs{thing} +(this time on its second occurrence), +as it will only be defined when \cs{next} is called, +not when \cs{next} is defined. + + +%\spoint[expand:write] Expansion and \cs{write} +\subsection{Expansion and \cs{write}} +\label{expand:write} + +The argument token list of \csidx{write} is treated in much +the same way as the replacement text of an \cs{edef}; +that is, expandable control sequences and active characters +are completely expanded. Unexpandable control sequences +are treated by \cs{write} as if they are prefixed +by \cs{string}. + +Because of the expansion performed by \cs{write}, +some care has to be taken when outputting control +sequences with \cs{write}. +Even more complications arise from the fact that +the expansion of the argument of \cs{write} is only performed +when it is shipped out. Here follows a worked-out +example. + +Suppose \cs{somecs} is a macro, and you +want to write the string +\begin{disp}\verb-\def\othercs-\lb {\italic the expansion of \cs{somecs}}\rb +\end{disp} +to a file. + +The first attempt is +\begin{verbatim} +\write\myfile{\def\othercs{\somecs}} +\end{verbatim} +This gives an error `undefined control sequence' for \cs{othercs}, +\altt +because the \cs{write} will try to expand that token. +Note that the \cs{somecs} is also expanded, +so that part is right. + +The next attempt is +\begin{verbatim} +\write\myfile{\def\noexpand\othercs{\somecs}} +\end{verbatim} +This is almost right, but not quite. The +statement written is +\begin{disp}\verb>\def\othercs>\lb{\italic expansion of \cs{somecs}}\rb\end{disp} +which looks right. + +However, writes \ldash and the expansion of their argument \rdash +are not executed +on the spot, but saved until the part of the page on which +they occur is shipped out (see Chapter~\ref{io}). +So, in the meantime, the value of \cs{somecs} may have +changed. In other words, the value written may not be the +value at the time the \cs{write} command was given. +Somehow, therefore, the current expansion must be +inserted in the write command. + +The following is an attempt at repair: +\begin{verbatim} +\edef\act{\write\myfile{\def\noexpand\othercs{\somecs}}} +\act +\end{verbatim} +Now the write command will be +\begin{disp}\verb>\write\myfile{\def\othercs{>\italic value of\/ + \verb>\somecs}}>\end{disp} +The \cs{noexpand} prevented the \cs{edef} from expanding +the \cs{othercs}, but after the definition it has disappeared, +so that execution of the write will again give an undefined control +sequence. The final solution is +\begin{verbatim} +\edef\act{\write\myfile + {\def \noexpand\noexpand \noexpand\othercs{\somecs}}} +\act +\end{verbatim} +In this case the write command caused by the expansion of \cs{act} +will be +\begin{disp}\verb>\write\myfile{\def\noexpand\othercs>\lb + {\italic current value of \cs{somecs}}\rb\end{disp} +and the string actually written is +\begin{disp}\verb>\def\othercs>\lb + {\italic current value of \cs{somecs}}\rb\end{disp} +This mechanism is the basis for cross-referencing +macros in several macro packages. + + +%\spoint Controlled expansion inside an \cs{edef} +\subsection{Controlled expansion inside an \cs{edef}} + +Sometimes you may need an \cs{edef} to evaluate current +\howto Control expansion inside an \cs{edef}\par +conditions, but you want to expand something in the replacement +text only to a certain level. Suppose that +\begin{verbatim} +\def\a{\b} \def\b{c} \def\d{\e} \def\e{f} +\end{verbatim} +is given, and you want to define \cs{g} as \cs{a} expanded +one step, followed by \cs{d} fully expanded. The following +works: +\begin{verbatim} +\edef\g{\expandafter\noexpand\a \d} +\end{verbatim} +Explanation: the \cs{expandafter} reaches over the \cs{noexpand} +to expand \cs{a} one step, after which the +sequence \verb-\noexpand\b- is left. + +This trick comes in handy when you need to +construct a control sequence with \cs{csname} inside +an \cs{edef}. The following sequence inside an \cs{edef} +\begin{verbatim} +\expandafter\noexpand\csname name\endcsname +\end{verbatim} +will expand exactly to \cs{name}, but not further. +As an example, suppose +\begin{verbatim} +\def\condition{true} +\end{verbatim} +has been given, then +\begin{verbatim} +\edef\setmycondition{\expandafter\noexpand + \csname mytest\condition\endcsname} +\end{verbatim} +will let \cs{setmycondition} expand to \cs{mytesttrue}. + +%\spoint Multiple prevention of expansion +\subsection{Multiple prevention of expansion} + +As was pointed out above, prefixing a command with +\cs{noexpand} prevents its expansion in commands +such as \cs{edef} and~\cs{write}. However, if a sequence of tokens +passes through more than one expanding command +stronger measures are needed. + +The following trick can be used: +in order to protect a command against expansion +it can be prefixed with \csidx{protect}. +During the stages of processing where expansion is +not desired the definition of \cs{protect} is +\begin{verbatim} +\def\protect{\noexpand\protect\noexpand} +\end{verbatim} +Later on, when the command is actually needed, +\cs{protect} is defined as +\begin{verbatim} +\def\protect{} +\end{verbatim} + +Why does this work? The expansion of +\begin{verbatim} +\protect\somecs +\end{verbatim} +is at first +\begin{verbatim} +\noexpand\protect\noexpand\somecs +\end{verbatim} +Inside an \cs{edef} this sequence is expanded further, +and the subsequent expansion is +\begin{verbatim} +\protect\somecs +\end{verbatim} +That is, the expansion is equal to the original sequence. + + +%\spoint More examples with \cs{relax} +\subsection{More examples with \cs{relax}} + +Above, a first example was given in which \cs{relax} served +to prevent \TeX\ from scanning too far. +Here are some more examples, using \cs{relax} to bound +numbers. + +After +\begin{verbatim} +\countdef\pageno=0 \pageno=1 +\def\Par{\par\penalty200} +\end{verbatim} +the sequence \begin{verbatim} +\Par\number\pageno +\end{verbatim} +is misunderstood as +\begin{verbatim} +\par\penalty2001 +\end{verbatim} +In this case it is sufficient to define +\begin{verbatim} +\def\Par{\par\penalty200 } +\end{verbatim} +as an \gr{optional space} is allowed to follow a number. + +Sometimes, however, such a simple escape is not possible. +Consider the definition +\begin{verbatim} +\def\ifequal#1#2{\ifnum#1=#2 1\else 0\fi} +\end{verbatim} +The question is whether the space after \verb-#2- +is necessary, superfluous, or simply wrong. +Calls such as \verb-\ifequal{27}{28}- that compare two +numbers (denotations) will correctly give \n1 or~\n0, +and the space is necessary to prevent misinterpretation. + +However, \verb-\ifequal\somecounter\othercounter- will +give \n{\char 32 1} if the counters are equal; in this +case the space could have been dispensed with. +The solution that works in both cases is +\begin{verbatim} +\def\ifequal#1#2{\ifnum#1=#2\relax 1\else 0\fi} +\end{verbatim} +Note that \cs{relax} is not expanded, so +\begin{verbatim} +\edef\foo{1\ifequal\counta\countb} +\end{verbatim} +will define \cs{foo} as either \verb-1\relax1- or~\n{10}. + +%\spoint[store:cat] Example: category code saving and restoring +\subsection{Example: category code saving and restoring} +\label{store:cat} + +In many applications it is necessary to change +\howto Save and restore category codes\par +the category code of a certain character during the +execution of some piece of code. If the writer of +that code is also the writer of the surrounding code, +s/he can simply change the category code back and forth. +However, if the surrounding code is by another author, +the value of the category code will have to be stored +and restored. + +Thus one would like to write +\begin{verbatim} +\storecat@ +... some code ... +\restorecat@ +\end{verbatim} +or maybe \begin{verbatim} +\storecat\% +\end{verbatim} +for characters that +are possibly a comment character (or ignored or invalid). +\alt +The basic idea is to define +\begin{verbatim} +\def\storecat#1{% + \expandafter\edef\csname restorecat#1\endcsname + {\catcode`#1=\the\catcode`#1}} +\end{verbatim} +so that, for instance, \verb>\storecat$> will define +the single control sequence `\verb>\restorecat$>' +(one control sequence) as \begin{verbatim} +\catcode`$=3 +\end{verbatim} +The macro \cs{restorecat} can then be implemented as +\begin{verbatim} +\def\restorecat#1{% + \csname restorecat#1\endcsname} +\end{verbatim} +Unfortunately, things are not so simple. + +The problems occur with active characters, because these +are expanded inside the \verb>\csname ... \endcsname> pairs. +One might be tempted to write \verb>\noexpand#1> everywhere, +but this is wrong. As was explained above, this is essentially +equal to \cs{relax}, which is unexpandable, and will therefore +lead to an error message when it appears between +\cs{csname} and \cs{endcsname}. The proper solution is then +to use \verb>\string#1>. For the case where the argument +was given as a control symbol (for example~\verb>\%>), +the escape character has to be switched off for a while. + +Here are the complete macros. The \cs{storecat} macro +gives its argument a default category code of~12. +\begin{verbatim} +\newcount\tempcounta % just a temporary +\def\csarg#1#2{\expandafter#1\csname#2\endcsname} +\def\storecat#1% + {\tempcounta\escapechar \escapechar=-1 + \csarg\edef{restorecat\string#1}% + {\catcode`\string#1= + \the\catcode\expandafter`\string#1}% + \catcode\expandafter`\string#1=12\relax + \escapechar\tempcounta} +\def\restorecat#1% + {\tempcounta\escapechar \escapechar=-1 + \csname restorecat\string#1\endcsname + \escapechar\tempcounta} +\end{verbatim} + +%\spoint Combining \cs{aftergroup} and boxes +\subsection{Combining \cs{aftergroup} and boxes} + +%\tracingmacros=2 \tracingcommands=2 +At times, one wants to construct a box and immediately +after it has been constructed to +do something with it. The \cs{aftergroup} command +can be used to put both the commands creating the box, +and the ones handling it, in one macro. + +As an example, here is a macro +\cs{textvcenter}\label{text:vcenter}\ +which defines a variant of the \cs{vcenter} box +\howto \cs{vcenter} outside math mode\par +(see page~\pageref{vcenter}\label{tvcenter}) +that can be used outside math mode. +\begin{verbatim} +\def\textvcenter + {\hbox \bgroup$\everyvbox{\everyvbox{}% + \aftergroup$\aftergroup\egroup}\vcenter} +\end{verbatim} +The idea is that the macro inserts \verb>\hbox {$>, +and that the matching \verb>$}> gets inserted +by the \cs{aftergroup} commands. In order to get the +\cs{aftergroup} commands inside the box, an +\cs{everyvbox} command is used. + +This macro can even be used with a \gr{box specification} +(see page~\pageref{box:spec}), for example +\begin{verbatim} +\textvcenter spread 8pt{\hbox{a}\vfil\hbox{b}} +\end{verbatim} +and because it is really just an \cs{hbox}, it can also +be used in a \cs{setbox} assignment. + +%\spoint More expansion +\subsection{More expansion} + +There is a particular charm to macros that work +purely by expansion. See the articles by +\cite{E2}, \cite{Jeffrey:lists}, and~\cite{Maus2}. + +%%%% end of input file [expand] + +%\InputFile:ifelsefi +%%%% this is input file [ifelsefi] +%\subject[if] Conditionals +\endofchapter +\chapter{Conditionals}\label{if} + +Conditionals are an indispensible tool for powerful macros. +\term conditional\par +\TeX\ has a large repertoire of conditionals for querying +such things as category codes or processing modes. +This chapter gives an inventory of the various conditionals, +and it treats the evaluation of +conditionals in detail. + +\begin{inventory} +\item [\cs{if}] + Test equality of character codes. + +\item [\cs{ifcat}] + Test equality of category codes. + +\item [\cs{ifx}] + Test equality of macro expansion, or equality of character code and + category code. + +\item [\cs{ifcase}] + Enumerated case statement. + +\item [\cs{ifnum}] + Test relations between numbers. + +\item [\cs{ifodd}] + Test whether a number is odd. + +\item [\cs{ifhmode}] + Test whether the current mode is (possibly restricted) horizontal mode. + +\item [\cs{ifvmode}] + Test whether the current mode is (possibly internal) vertical mode. + +\item [\cs{ifmmode}] + Test whether the current mode is (possibly display) math mode. + +\item [\cs{ifinner}] + Test whether the current mode is an internal mode. + +\item [\cs{ifdim}] + Compare two dimensions. + +\item [\cs{ifvoid}] + Test whether a box register is empty. + +\item [\cs{ifhbox}] + Test whether a box register contains a horizontal box. + +\item [\cs{ifvbox}] + Test whether a box register contains a vertical box. + +\item [\cs{ifeof}] + Test for end of input stream or non-existence of file. + +\item [\cs{iftrue}] + A test that is always true. +\item [\cs{iffalse}] + A test that is always false. +\item [\cs{fi}] + Closing delimiter for all conditionals. + +\item [\cs{else}] + Select \gr{false text} of a conditional + or default case of \cs{ifcase}. + +\item [\cs{or}] + Separator for entries of an \cs{ifcase}. + +\item [\cs{newif}] + Create a new test. + +\end{inventory} + +%\point The shape of conditionals +\section{The shape of conditionals} + +Conditionals in \TeX\ have one of the following two forms +\cstoidx else\par\cstoidx fi\par +\begin{disp}\cs{if...}\gr{test tokens}\gr{true text}\cs{fi}\nl + \cs{if...}\gr{test tokens}\gr{true text}\cs{else}% + \gr{false text}\cs{fi}\end{disp} +where the \gr{test tokens} are zero or more tokens, depending on +the particular conditional; the \gr{true text} is a series of tokens +to be processed if the test turns out true, and the \gr{false text} +is a series of tokens to be processed if the test turns out false. +Both the \gr{true text} and the \gr{false text} can be empty. + +The exact process of how \TeX\ expands conditionals is treated +below. + +%\point Character and control sequence tests +\section{Character and control sequence tests} + +Three tests exist for testing character tokens and +control sequence tokens. + +%\spoint \cs{if} +\subsection{\cs{if}} + +Equality of character codes can be tested by +\cstoidx if\par +\begin{Disp}\cs{if}\gr{token$_1$}\gr{token$_2$}\end{Disp} +In order to allow the tokens to be control sequences, +\TeX\ assigns character code~256 to control sequences, +the lowest positive number that is not the character code of a +character token (remember that the legal character codes +are~0--255). + +Thus all control sequences are equal as far as \cs{if} is +concerned, and they are unequal to all character tokens. +As an example, this fact can be used to define +\howto Test whether a token is a control sequence\par +\begin{verbatim} +\def\ifIsControlSequence#1{\if\noexpand#1\relax} +\end{verbatim} +which tests whether a token is a control sequence token +instead of a character token (its result is unpredictable +if the argument is a \verb>{...}> group). + +After \cs{if} \TeX\ will expand until two unexpandable +tokens are obtained, so it is necessary to prefix +expandable control sequences and active characters +with \cs{noexpand} when testing them with~\cs{if}. + +\begin{example} After +\begin{verbatim} +\catcode`\b=13 \catcode`\c=13 \def b{a} \def c{a} \let\d=a +\end{verbatim} +we find that +\begin{tdisp} +\verb-\if bc- is true, because both \n b and \n c expand to \n a,\nl +\verb-\if\noexpand b\noexpand c- is false, and\nl +\verb-\if b\d- is true because \n{b} expands to the character~\n{a}, + and \cs{d} is an implicit character token~\n{a}. +\end{tdisp} +\end{example} + +%\spoint \cs{ifcat} +\subsection{\cs{ifcat}} + +The \cs{if} test ignores category codes; these can be tested +\cstoidx ifcat\par +by \begin{Disp}\cs{ifcat}\gr{token$_1$}\gr{token$_2$}\end{Disp} + +This test is a lot like \cs{if}: \TeX\ expands after it +until unexpandable tokens remain. For this test +control sequences +are considered to have category code~16 +(ordinarily, category codes are in the range~0--15), which makes them +all equal to each other, and different from all character +tokens. + +%\spoint \cs{ifx} +\subsection{\protect\cs{ifx}} + +Equality of tokens is tested in a stronger sense than +\cstoidx ifx\par +the above by \begin{Disp}\cs{ifx}\gr{token$_1$}\gr{token$_2$}\end{Disp} + +\begin{itemize}\item Character tokens are equal for \cs{ifx} if +they have the same character code and category code. + \item Control sequence tokens are equal if they represent the +same \TeX\ primitive, or have been similarly defined by +\cs{font}, \cs{countdef}, or some such. For example, +\begin{verbatim} +\let\boxhor=\hbox \ifx\boxhor\hbox %is true +\font\a=cmr10 \font\b=cmr10 \ifx\a\b %is true +\end{verbatim} +\item Control sequences are also equal if they are +macros with the same parameter text and replacement text, +and the same status with respect to \cs{outer} and~\cs{long}. +For example, +\begin{verbatim} +\def\a{z} \def\b{z} \def\c1{z} \def\d{\a} +\ifx\a\b %is true +\ifx\a\c %is false +\ifx\a\d %is false +\end{verbatim} +\end{itemize} + +Tokens following this test are not expanded. + +By way of example of the use of \cs{ifx} consider string testing. +A simple implementation of string testing in \TeX\ is as follows: +\begin{verbatim} +\def\ifEqString#1#2{\def\testa{#1}\def\testb{#2}% + \ifx\testa\testb} +\end{verbatim} +The two strings are used as the replacement text of two macros, +and equality of these macros is tested. +This is about as efficient as string testing can get: +\TeX\ will traverse the definition texts of the +macros \cs{testa} and \cs{testb}, which has precisely the +right effect. + +As another example, one can test whether a control sequence is defined +by\howto Test whether a control sequence is (un)defined\par +\begin{verbatim} +\def\ifUnDefinedCs#1{\expandafter + \ifx\csname#1\endcsname\relax} +\ifUnDefinedCs{parindent} %is not true +\ifUnDefinedCs{undefined} %is (one hopes) true +\end{verbatim} +This uses the fact that a \verb>\csname...\endcsname> command +is equivalent to \cs{relax} if the control sequence +has not been defined before. Unfortunately, this test also +turns out true if a control sequence has been \cs{let} to +\cs{relax}. + +%\point Mode tests +\section{Mode tests} + +In order to determine in which of the six modes +(see Chapter~\ref{hvmode}) \TeX\ +is currently operating, the tests \csidx{ifhmode}, +\csidx{ifvmode}, \csidx{ifmmode}, and~\csidx{ifinner} +are available. + +\begin{itemize}\item\cs{ifhmode} is true if \TeX\ is in horizontal mode +or restricted horizontal mode. +\item\cs{ifvmode} is true if \TeX\ is in vertical mode or +internal vertical mode. +\item\cs{ifmmode} is true if \TeX\ is in math mode or display +math mode.\end{itemize} + +The \cs{ifinner} test is true if \TeX\ is in any of the three +internal modes: restricted horizontal mode, internal vertical +mode, and non-display math mode. + +%\point Numerical tests +\section{Numerical tests} + +Numerical relations between \gr{number}s can be tested +\cstoidx ifnum\par +with \begin{disp}\cs{ifnum}\gr{number$_1$}\gr{relation}% +\gr{number$_2$}\end{disp} +where the relation is a character \n{<}, \n{=}, or~\n{>}, +of category~12. + +Quantities such as glue can be used as a number here +through the conversion to scaled points, and \TeX\ +will expand in order to arrive at the two \gr{number}s. + +Testing for odd or even numbers can be done with \csidx{ifodd}: +the test\begin{disp}\cs{ifodd}\gr{number}\end{disp} +is true if the \gr{number} is odd. + +%\point Other tests +\section{Other tests} + +%\spoint Dimension testing +\subsection{Dimension testing} + +Relations between \gr{dimen} values (Chapter~\ref{glue}) +can be tested with +\csidx{ifdim} using the same three relations as in \cs{ifnum}. + +%\spoint Box tests +\subsection{Box tests} + +Contents of box registers (Chapter~\ref{boxes}) can be tested with +\cstoidx ifhbox\par\cstoidx ifvbox\par\cstoidx ifvoid\par +\begin{disp}\cs{ifvoid}\gr{8-bit number}\end{disp} +which is true if the register contains no box, +\begin{disp}\cs{ifhbox}\gr{8-bit number}\end{disp} +which is true if the register contains a horizontal box, and +\begin{disp}\cs{ifvbox}\gr{8-bit number}\end{disp} +which is true if the register contains a vertical box. + +%\spoint I{/}O tests +\subsection{I{/}O tests} + +The status of input streams (Chapter~\ref{io}) can be tested with +\cstoidx ifeof\par +the end-of-file test +\cs{ifeof}\gr{number}, which is only false +if the number is in the range 0--15, and the corresponding +stream is open and not fully read. In particular, this test +is true if the file name connected +to this stream (through \cs{openin}) +does not correspond to an existing file. +See the example on page~\pageref{ex:eof}. + +%\spoint Case statement +\subsection{Case statement} + +The \TeX\ case statement is called \cs{ifcase}; +\cstoidx ifcase\par\cstoidx or\par +its syntax is\begin{disp}\cs{ifcase}\gr{number}\gr{case$_0$}\cs{or}% +\n{...}\cs{or}\gr{case$_n$}\cs{else}\gr{other cases}\cs{fi} +\end{disp} where for $n$ cases there are $n-1$ \cs{or} +control sequences. Each of the \gr{case$_i$} +parts can be empty, +and the \cs{else}\gr{other cases} part is optional. + +%\spoint Special tests +\subsection{Special tests} + +The tests \cs{iftrue} and \cs{iffalse} are always +\cstoidx iftrue\par\cstoidx iffalse\par +true and false respectively. +They are mainly useful as tools in macros. + +For instance, the sequences \begin{verbatim} +\iftrue{\else}\fi +\end{verbatim} +and \begin{verbatim} +\iffalse{\else}\fi +\end{verbatim} +yield a left and right +brace respectively, but they have balanced braces, so they +can be used inside a macro replacement text. + +The \cs{newif} macro, treated below, +provides another use of \cs{iftrue} and \cs{iffalse}. +On page 260 of \TeXbook\ these control sequences +are also used in an interesting manner. + +%\point[newif:def] The \cs{newif} macro +\section{The \protect\cs{newif} macro} +\label{newif:def} + +The plain format defines an (outer) macro \csidx{newif} by +which the user can define new conditionals. +If the user defines \begin{verbatim} +\newif\iffoo +\end{verbatim} +\TeX\ defines three new control sequences, +\cs{footrue} and \cs{foofalse} with which the user can set +the condition, and \cs{iffoo} which tests the `foo' condition. + +The macro call \verb-\newif\iffoo- expands to +\begin{verbatim} +\def\footrue{\let\iffoo=\iftrue} \def\foofalse{\let\iffoo=\iffalse} +\foofalse +\end{verbatim} +The actual definition, especially the part that ensures that +the \cs{iffoo} indeed starts with \cs{if}, is a pretty hack. +An explanation follows here. +This uses concepts from Chapters~\ref{macro} +and~\ref{expand}. + +The macro \cs{newif} starts as follows: +\begin{verbatim} +\outer\def\newif#1{\count@\escapechar \escapechar\m@ne +\end{verbatim} +This saves the current escape character in \cs{count@}, and +sets the value of \cs{escapechar} to~\n{-1}. +The latter action has the +effect that no escape character is used in the output +of \cs{string}\gr{control sequence}. + +An auxiliary macro \verb>\if@> is defined by +\begin{verbatim} +{\uccode`1=`i \uccode`2=`f \uppercase{\gdef\if@12{}}} +\end{verbatim} +Since the uppercase command changes only character codes, and +not category codes, the macro \cs{if@} now has +to be followed by the characters \n{if} of category~12. +Ordinarily, these characters have category code~11. +In effect this +macro then eats these two characters, and \TeX\ complains if +they are not present. + +Next there is a macro \verb>\@if> defined by +\begin{verbatim} +\def\@if#1#2{\csname\expandafter\if@\string#1#2\endcsname} +\end{verbatim} +which will be called like \verb>\@if\iffoo{true}> and +\verb>\@if\iffoo{false}>. + +Let us examine the call \verb>\@if\iffoo{true}>. +\begin{itemize}\item The \cs{expandafter} reaches over the \verb>\if@> +to expand \cs{string} first. The part \verb>\string\iffoo> +expands to \n{iffoo} because the escape character is not printed, +and all characters have category~12. +\item The \verb>\if@> eats the first two characters +\n i$_{12}$\n f$_{12}$ of this. +\item As a result, the final expansion of \verb>\@if\iffoo{true}> +is then \begin{verbatim} +\csname footrue\endcsname +\end{verbatim} +\end{itemize} + +Now we can treat the relevant parts of \cs{newif} itself: +\begin{verbatim} +\expandafter\expandafter\expandafter + \edef\@if#1{true}{\let\noexpand#1=\noexpand\iftrue}% +\end{verbatim} + +The three \cs{expandafter} commands may look intimidating, so let us +take one step at a time. +\begin{itemize}\item One \cs{expandafter} is necessary to reach over the \cs{edef}, +such that \verb>\@if> will expand: +\begin{verbatim} +\expandafter\edef\@if\iffoo{true} +\end{verbatim} +gives +\begin{verbatim} +\edef\csname footrue\endcsname +\end{verbatim} +\item Then another \cs{expandafter} is necessary to activate +\altt +the \cs{csname}: +\begin{verbatim} +\expandafter \expandafter \expandafter \edef \@if ... +% new old new +\end{verbatim} +\item This makes the final expansion +\begin{verbatim} +\edef\footrue{\let\noexpand\iffoo=\noexpand\iftrue} +\end{verbatim} +\end{itemize} + +After this follows a similar statement for the \n{false} case: +\begin{verbatim} + \expandafter\expandafter\expandafter + \edef\@if#1{false}{\let\noexpand#1=\noexpand\iffalse}% +\end{verbatim} +The conditional starts out false, and the escape character +has to be reset: +\begin{verbatim} + \@if#1{false}\escapechar\count@} +\end{verbatim} + + +%\point Evaluation of conditionals +\section{Evaluation of conditionals} + +\TeX's conditionals behave differently from those +\term evaluation! conditionals\par\term conditionals! evaluation of\par +in ordinary programming languages. In many instances +one may not notice the difference, but in certain contexts +it is important to know precisely what happens. + +When \TeX\ evaluates a conditional, it first determines +what is to be tested. This in itself may involve some +expansion; as we saw in the previous chapter, +only after an \cs{ifx} test +does \TeX\ not expand. After all other tests \TeX\ will +expand tokens until the extent of the test and the tokens +to be tested have been determined. On the basis of the outcome +of this test the \gr{true text} and the \gr{false text} +are either expanded or skipped. + +For the processing of the parts of the conditional +let us consider some cases separately. +\begin{itemize} +\item \verb>\if... ... \fi> and the result of the test is false. + After the test \TeX\ will start skipping material + without expansion, without counting braces, but balancing + nested conditionals, until a \cs{fi} token is encountered. + If the \cs{fi} is not found an error message results + at the end of the file: + \begin{disp}\tt Incomplete \cs{if...}; all text was ignored after line \n{...} + \end{disp} where the line number indicated is that of the line + where \TeX\ started skipping, that is, where the conditional + occurred. + +\item \verb>\if... \else ... \fi> and the result of the test is false. + Any material in between the condition and the \cs{else} is skipped + without expansion, without counting braces, but balancing nested + conditionals. + + The \cs{fi} token can be the result of expansion; if it never + turns up \TeX\ will give a diagnostic message + \begin{disp}\tt \cs{end} occurred when \cs{if...} on line \n{...} + was incomplete\end{disp} + This sort of error is not visible in the output. + + This point plus the previous may jointly be described as follows: + after a false condition \TeX\ skips until an \cs{else} or \cs{fi} + is found; any material in between \cs{else} and \cs{fi} is processed. + +\item \verb>\if... ... \fi> and the result of the test is true. + \TeX\ will start processing the material following the condition. + As above, the \cs{fi} token may be inserted by expansion of + a macro. + +\item \verb>\if... \else ... \fi> and the result of the test is true. + Any material following the condition is processed until the \cs{else} + is found; then \TeX\ skips everything until the matching \cs{fi} + is found. + + This point plus the previous may be described as follows: + after a true test \TeX\ starts processing material until + an \cs{else} or \cs{fi} is found; if an \cs{else} is found + \TeX\ skips until it finds the matching \cs{fi}. +\end{itemize} + + +%\point Assorted remarks +\section{Assorted remarks} + +%\spoint The test gobbles up tokens +\subsection{The test gobbles up tokens} + +A common mistake is to write the following: +\begin{verbatim} +\ifnum\x>0\someaction \else\anotheraction \fi +\end{verbatim} +which has the effect that the \verb.\someaction. is expanded, +regardless of whether the test succeeds or not. +The reason for this is that \TeX\ evaluates the input stream until +it is certain that it has found the arguments to be tested. +In this case it is perfectly possible for the \verb.\someaction. +to yield a digit, so it is expanded. The remedy is to insert +\altt +a space or a \cs{relax} control sequence +after the last digit of the number to be tested. + +%\spoint The test wants to gobble up the \cs{else} or \cs{fi} +\subsection{The test wants to gobble up the \cs{else} or \cs{fi}} + +The same mechanism that underlies the phenomenon in the previous +point can lead to even more surprising effects if \TeX\ +bumps into an \verb.\else., \verb.\or., or \verb.\fi. +while still busy determining the extent of the test itself. + +Recall that \verb.\pageno. is a synomym for \verb.\count0., and +consider the following examples: +\begin{verbatim} +\newcount\nct \nct=1\ifodd\pageno\else 2\fi 1 +\end{verbatim} +and +\begin{verbatim} +\newcount\nct \nct=1\ifodd\count0\else 2\fi 1 +\end{verbatim} +The first example will assign either 11 or~121 to \cs{nct}, +but the second one will assign 1 or~121. +The explanation is that +in cases like the second, where +\altt +an \verb.\else. is encountered while the +test still has not been delimited, a \verb.\relax. is inserted. +In the case that \verb.\count0. is odd the result will thus be \verb.\relax., +and the example will yield \begin{verbatim} +\nct=1\relax2 +\end{verbatim} +which will assign~1 to \cs{nct}, and print~2. + + +%\spoint[after:cond] Macros and conditionals; the use of \cs{expandafter} +\subsection{Macros and conditionals; the use of \cs{expandafter}} +\label{after:cond} + +Consider the following example: +\begin{verbatim} +\def\bold#1{{\bf #1}} \def\slant#1{{\sl #1}} +\ifnum1>0 \bold \else \slant \fi {some text} ... +\end{verbatim} +This will make not only `some text', +but {\sl all\/} subsequent text bold. +Also, at the end of the job there will be a notice that +`end occurred inside a group at level~1'. +Switching on \cs{tracingmacros} reveals that the argument +of \verb.\bold. was \verb.\else.. +This means that, after expansion of \verb.\bold., +the input stream looked like +\begin{verbatim} +\ifnum1>0 {\bf \else }\fi {some text} rest of the text +\end{verbatim} +so the closing brace was skipped as part of the \gram{false text}. +Effectively, then, the resulting stream is +\begin{verbatim} +{\bf {some text} rest of the text +\end{verbatim} +which is unbalanced. + +One solution to this sort of problem would be to write +\begin{verbatim} +\ifnum1>0 \let\next=\bold \else \let\next=\slant \fi \next +\end{verbatim} +but a solution using \cs{expandafter} is also possible: +\begin{verbatim} +\ifnum1>0 \expandafter \bold \else \expandafter \slant \fi +\end{verbatim} +This works, because the \cs{expandafter} commands let \TeX\ determine +the boundaries of the \gram{true text} and the \gram{false text}. + +In fact, the second solution may be preferred over the first, +since conditionals are handled by the expansion processor, +and the \cs{let} statements are tackled only by the execution +processor; that is, they are not expandable. +Thus the second solution will (and the first will not) +work, for instance, +inside an~\cs{edef}. + +Another example with \cs{expandafter} is the sequence +\begin{verbatim} +\def\get#1\get{ ... } +\expandafter \get \ifodd1 \ifodd3 5\fi \fi \get +\end{verbatim} +This gives\begin{verbatim} +#1<- \ifodd3 5\fi \fi +\end{verbatim} +and +\begin{verbatim} +\expandafter \get \ifodd2 \ifodd3 5\fi\fi \get +\end{verbatim} +gives\begin{verbatim} +#1<- +\end{verbatim} +This illustrates again that the result of evaluating a +conditional is not the final expansion, but the start +of the expansion of the \gr{true text} or \gr{false text}, +depending on the outcome of the test. + +A detail should be noted: with \cs{expandafter} +it is possible that the \verb.\else. is encountered +before the \gram{true text} has been expanded completely. +This raises the question as to the exact timing of expansion +and skipping. +In the example +\begin{verbatim} +\def\hello{\message{Hello!}} +\ifnum1>0 \expandafter \hello \else \message{goodbye} \bye +\end{verbatim} +the error message caused by the missing \verb.\fi. is given +without \verb.\hello. ever having been expanded. +The conclusion must be that the \gram{false text} is +skipped as soon as it has been located, even if this is at a time +when the \gram{true text} has not been expanded completely. + +%\spoint Incorrect matching +\subsection{Incorrect matching} + +\TeX's matching of \verb.\if., \verb.\else., and \verb.\fi. +is easily upset. For instance, \TeXbook\ warns you that +you should not say \begin{verbatim} + \let\ifabc=\iftrue +\end{verbatim} +inside a +conditional, because if this text is skipped \TeX\ sees +at least one \verb.\if. to be matched. + +The reason for this is that when \TeX\ is skipping +it recognizes all \cs{if...}, \cs{or}, \cs{else}, and \cs{fi} +tokens, and everything that has been declared a synonym of +such a token by \cs{let}. In \verb>\let\ifabc=\iftrue> +\TeX\ will therefore at least see the \cs{iftrue} as +the opening of a conditional, and, if the current meaning +of \cs{ifabc} was for instance \cs{iffalse}, it will also +be considered as the opening of a conditional statement. + +As another example, if +\begin{verbatim} + \csname if\sometest\endcsname \someaction \fi +\end{verbatim} +is skipped as part of conditional text, +the \verb.\fi. will unintentionally close the +outer conditional. + +It does not help to enclose such potentially dangerous +constructs inside a group, because grouping is independent of +conditional structure. Burying such commands inside macros is +the safest approach. + +Sometimes another solution is possible, however. +The \cs{loop} macro of plain \TeX\ (see page~\pageref{loop:ex}) +is used as \begin{verbatim} +\loop ... \if ... \repeat +\end{verbatim} +where the \cs{repeat} is not an actually executable +command, but is merely a delimiter: +\begin{verbatim} +\def\loop#1\repeat{ ... } +\end{verbatim} +Therefore, +by declaring \begin{verbatim} +\let\repeat\fi +\end{verbatim} +the \cs{repeat} balances the \cs{if...} that terminates +the loop, and it becomes possible to have loops in +skipped conditional text. + +%\spoint Conditionals and grouping +\subsection{Conditionals and grouping} + +It has already been mentioned above that group nesting in \TeX\ +is independent of conditional nesting. +The reason for this is that conditionals are handled by the +expansion part of \TeX; in that stage braces are just +unexpandable tokens that require no special treatment. +Grouping is only performed in the later stage of execution +processing. + +An example of this independence is now given. +One may write a macro that yields part of +a conditional: +\begin{verbatim} +\def\elsepart{\else \dosomething \fi} +\end{verbatim} +The other way around, the following macros +yield a left brace and a right brace respectively: +\begin{verbatim} +\def\leftbrace{\iftrue{\else}\fi} +\def\rightbrace{\iffalse{\else}\fi} +\end{verbatim} +Note that braces in these definitions are properly nested. + +%\spoint A trick +\subsection{A trick} + +In some contexts it may be hard to get rid of +\cs{else} or \cs{fi} tokens in a proper +manner. The above approach with \cs{expandafter} +works only if there is a limited number of tokens involved. +In other cases the following trick may provide a way out: +\begin{verbatim} +\def\hop#1\fi{\fi #1} +\end{verbatim} +Using this as +\begin{disp}\verb>\if... \hop >\gr{lots of tokens}\verb>\fi>\end{disp} +will place the tokens outside the conditional. +This is for instance used in~\cite{E2}. + +As a further example of this sort of trick, +consider the problem (suggested to me and solved by +Alan Jeffrey) of implementing a conditional +\verb-\ifLessThan#1#2#3#4- +such that the arguments corresponding to \verb-#3- or +\verb-#4- result, depending on whether \verb-#1- is +less than \verb-#2- or not. + +The problem here is how to get rid of the \cs{else} and the~\cs{fi}. +The \ldash or at least, one \rdash solution is to scoop them up +as delimiters for macros: +\begin{verbatim} +\def\ifLessThan#1#2{\ifnum#1<#2\relax\taketrue \else \takefalse \fi} +\def\takefalse\fi#1#2{\fi#2} +\def\taketrue\else\takefalse\fi#1#2{\fi#1} +\end{verbatim} +Note that \cs{ifLessThan} has only two parameters +(the things to be tested); however, its +result is a macro that +chooses between the next two arguments. + +%\spoint More examples of expansion in conditionals +\subsection{More examples of expansion in conditionals} + +Above, the macro \cs{ifEqString} was given +\alt +that compares two strings: +\howto Compare two strings\par +\begin{verbatim} +\def\ifEqString#1#2% + {\def\csa{#1}\def\csb{#2}\ifx\csa\csb } +\end{verbatim} +However, this macro relies on \cs{def}, which is not an +expandable command. If we need a string tester that will +work, for instance, inside an \cs{edef}, we need some +more ingenuity (this solution was taken from~\cite{E2}). +The basic principle of this solution is to compare the strings +one character at a time. Macro delimiting by \cs{fi} is used; +this was explained above. + +First of all, the \cs{ifEqString} call is replaced by a +sequence \verb>\ifAllChars ...\Are ...\TheSame>, and both +strings are delimited by a dollar sign, which is not supposed +to appear in the strings themselves. +\begin{verbatim} +\def\ifEqString + #1#2{\ifAllChars#1$\Are#2$\TheSame} +\end{verbatim} +The test for equality of characters first determines +whether either string has ended. If both have ended, the original +strings were equal; if only one has ended, they were of unequal +length, hence unequal. If neither string has ended, we test +whether the first characters are equal, and if so, we make a recursive +call to test the remainder of the string. +\begin{verbatim} +\def\ifAllChars#1#2\Are#3#4\TheSame + {\if#1$\if#3$\say{true}% + \else \say{false}\fi + \else \if#1#3\ifRest#2\TheSame#4\else + \say{false}\fi\fi} +\def\ifRest#1\TheSame#2\else#3\fi\fi + {\fi\fi \ifAllChars#1\Are#2\TheSame} +\end{verbatim} +The \cs{say} macro is supposed to give \cs{iftrue} for +\verb>\say{true}> and \cs{iffalse} for \verb>\say{false}>. +Observing that all calls to this macro occur two conditionals deep, +we use the `hop' trick explained above as follows. +\begin{verbatim} +\def\say#1#2\fi\fi + {\fi\fi\csname if#1\endcsname} +\end{verbatim} + +Similar to the above example, let us write a macro +that will test lexicographic (`dictionary') precedence +of two strings: +\howto Compare two strings lexicographically\par +\begin{verbatim} +\let\ex=\expandafter +\def\ifbefore + #1#2{\ifallchars#1$\are#2$\before} +\def\ifallchars#1#2\are#3#4\before + {\if#1$\say{true\ex}\else + \if#3$\say{false\ex\ex\ex}\else + \ifnum`#1>`#3 \say{false% + \ex\ex\ex\ex\ex\ex\ex}\else + \ifnum`#1<`#3 \say{true% + \ex\ex\ex\ex\ex\ex\ex + \ex\ex\ex\ex\ex\ex\ex\ex}\else + \ifrest#2\before#4\fi\fi\fi\fi} +\def\ifrest#1\before#2\fi\fi\fi\fi + {\fi\fi\fi\fi + \ifallchars#1\are#2\before} +\def\say#1{\csname if#1\endcsname} +\end{verbatim} +In this macro a slightly +different implementation of \cs{say} is used. + +Simplified, a call to \cs{ifbefore} will eventually lead to a situation +that looks (in the `true' case) like +\begin{verbatim} +\ifbefore{...}{...} + \if... %% some comparison that turns out true + \csname iftrue\expandafter\endcsname + \else .... \fi + ... %% commands for the `before' case +\else + ... %% commands for the `not-before' case +\fi +\end{verbatim} +When the comparison has turned out true, \TeX\ will start processing +the \gr{true text}, and make a mental note to remove any +\verb>\else ... \fi> part once an \cs{else} token is seen. +Thus, the sequence +\begin{verbatim} +\csname iftrue\expandafter\endcsname \else ... \fi +\end{verbatim} +is replaced by \begin{verbatim} + \csname iftrue\endcsname +\end{verbatim} +as the \cs{else} is seen while \TeX\ is still processing +\verb>\csname...\endcsname>. + +Calls to \cs{say} occur inside nested conditionals, so +the number of \cs{expandafter} commands necessary may be +\alt +larger than~1: for level two it is~3, for level three +it is~7, and for level~4 it is 15. Slightly more compact +implementations of this macro do exist. + +%%%% end of input file [ifelsefi] + +%\InputFile:token +%%%% this is input file [token] +%\subject[token] Token Lists +\endofchapter +\chapter{Token Lists}\label{token} + +\TeX\ has only one type of data structure: the token list. +\term token! lists\par\term list !token\par +There are token list registers that are available to the user, +and \TeX\ has some special token lists: the \cs{every...} +variables, \cs{errhelp}, and \cs{output}. + + +\begin{inventory} +\item [\cs{toks}] + Prefix for a token list register. + +\item [\cs{toksdef}] + Define a control sequence to be a synonym for + a~\cs{toks} register. + +\item [\cs{newtoks}] + Macro that allocates a token list register. + +\end{inventory} + +%\point Token lists +\section{Token lists} + +Token lists are the only type of data structure that \TeX\ knows. +They can contain character tokens and control sequence tokens. +Spaces in a token list are significant. +The only operations on token lists are assignment and +unpacking. + +\TeX\ has 256 token list registers \verb|\toks|$nnn$ that can be +allocated using the macro \verb|\newtoks|, or explicitly +assigned by \cs{toksdef}; see below. + +%\point Use of token lists +\section{Use of token lists} + +Token lists are assigned by a \gr{variable assignment}, +which is in this case takes one of the forms +\begin{disp}\gr{token variable}\gr{equals}\gr{general text}\nl + \gr{token variable}\gr{equals}\gr{filler}\gr{token variable}\end{disp} +Here a \gr{token variable} is an explicit \cs{toks}$nnn$ +register, something that has been defined to such a register +by \cs{toksdef} (probably hidden in \cs{newtoks}), +or one of the special \gr{token parameter} +lists below. +A~\gr{general text} has an explicit closing brace, but the +open brace can be implicit. + +Examples of token lists are (the first two lines are equivalent): +\begin{verbatim} +\toks0=\bgroup \a \b cd} +\toks0={\a \b cd} +\toks1=\toks2 +\end{verbatim} + +Unpacking a token list is done by the command \cs{the}: +the expansion of \cs{the}\gr{token variable} is the +sequence of tokens that was in the token list. + +Token lists have a special behaviour in \cs{edef}: +when prefixed by \verb|\the| they are unpacked, +but the resulting tokens +are not evaluated further. Thus +\begin{verbatim} +\toks0={\a \b} \edef\SomeCs{\the\toks0} +\end{verbatim} +gives +\begin{verbatim} +\SomeCs: macro:-> \a \b +\end{verbatim} +This is in contrast to what happens ordinarily in an~\cs{edef}; +see page~\pageref{expand:edef}. + + +%\point \gr{token parameter} +\section{\gr{token parameter}} + +There are in \TeX\ a number of token lists that are automatically +inserted at certain points. These \gr{token parameter}s are +the following: +\begin{description} \item [\cs{output}] + this token list is inserted + whenever \TeX\ decides it has sufficient material for a page, + or when the user forces activation by a penalty~$\leq-10\,000$ + in vertical mode + (see Chapter~\ref{output}); +\item [\cs{everypar}] + is inserted when \TeX\ switches from external or internal + vertical mode to unrestricted horizontal mode + (see Chapter~\ref{par:start}); +\item [\cs{everymath}] + is inserted after a single math-shift character that starts + a formula; +\item [\cs{everydisplay}] + is inserted after a double math-shift character that starts + a display formula; +\item [\cs{everyhbox}] + is inserted when an \cs{hbox} begins (see Chapter~\ref{boxes}); +\item [\cs{everyvbox}] + is inserted when a vertical box begins (see Chapter~\ref{boxes}); +\item [\cs{everyjob}] + is inserted when a job begins (see Chapter~\ref{run}); +\item [\cs{everycr}] + is inserted in alignments after \cs{cr} or a non-redundant + \cs{crcr} (see Chapter~\ref{align}); +\item [\cs{errhelp}] + contains tokens to supplement an \cs{errmessage} + (see Chapter~\ref{error}). +\end{description} + +A \gr{token parameter} behaves the same as an explicit \cs{toks}$nnn$ +list, or a quantity defined by \cs{toksdef}. + +%\point Token list registers +\section{Token list registers} + +Token lists can be stored in \csidx{toks} registers: +\begin{Disp}\cs{toks}\gr{8-bit number}\end{Disp} +which is a \gr{token variable}. +Synonyms for token list registers can be made by the \gr{registerdef} +command \csidx{toksdef} in a \gr{shorthand definition}: +\begin{Disp}\cs{toksdef}\gr{control sequence}\gr{equals}\gr{8-bit number} +\end{Disp} A control sequence defined this way is called +a \gr{toksdef token}, and this is also a token variable +(the remaining third kind of token variable is +the \gr{token parameter}). + +The plain \TeX\ macro \csidx{newtoks} uses \cs{toksdef} to +allocate unused token list registers. This macro is \cs{outer}. + +%\point Examples +\section{Examples} + +Token lists are probably among the least obvious components +of \TeX: most \TeX\ users will never find occasion for their use, +but format designers and other macro writers +can find interesting applications. +Following are some examples of the sorts of things that can be +done with token lists. + +%\spoint Operations on token lists: stack macros +\subsection{Operations on token lists: stack macros} + +The number of primitive operations available for token lists is +\howto Stack macros\par +rather limited: assignment and unpacking. However, these are +sufficient to implement other operations such as appending. + +Let us say we have allocated a token register +\begin{verbatim} +\newtoks\list \list={\c} +\end{verbatim} +and we want to add tokens to it, +\alt +using the syntax +\begin{verbatim} +\Prepend \a \b (to:)\list +\end{verbatim} +such that \begin{verbatim} +\showthe\list +\end{verbatim} +gives \begin{verbatim} +> \a \b \c . +\end{verbatim} +For this the original list has to be unpacked, and +\alt +the new tokens followed by the old contents have to assigned +again to the register. Unpacking can be done with \cs{the} +inside an \cs{edef}, so we arrive at the following macro: +\begin{verbatim} +\def\Prepend#1(to:)#2{\toks0={#1}% + \edef\act{\noexpand#2={\the\toks0 \the#2}}% + \act} +\end{verbatim} +Note that the tokens that are to be added are first packed +\alt +into a temporary token list, which is then again unpacked +inside the \cs{edef}. Including them directly would have +led to their expansion. + +Next we want to use token lists as a sort of stack: +we want a `pop' operation that removes the first element +from the list. Specifically, +\begin{verbatim} +\Pop\list(into:)\first +\show\first \showthe\list +\end{verbatim} +should give +\begin{verbatim} +> \first=macro: +->\a . +\end{verbatim} +and for the remaining list +\begin{verbatim} + +> \b \c . +\end{verbatim} + +Here we make creative use of delimited and undelimited +parameters. With an \cs{edef} we unpack the list, +and the auxiliary macro \cs{SplitOff} scoops up the elements +as one undelimited argument, the first element, and one +delimited argument, the rest of the elements.\begin{verbatim} +\def\Pop#1(into:)#2{% + \edef\act{\noexpand\SplitOff\the#1% + (head:)\noexpand#2(tail:)\noexpand#1}% + \act} +\def\SplitOff#1#2(head:)#3(tail:)#4{\def#3{#1}#4={#2}} +\end{verbatim} + +%\spoint Executing token lists +\subsection{Executing token lists} + +The \cs{the} operation for unpacking token lists was used above +only inside an \cs{edef}. Used on its own it has the effect +of feeding the tokens of the list to \TeX's expansion mechanism. +If the tokens have been added to the list in a uniform syntax, +this gives rise to some interesting possibilities. + +Imagine that we are implementing the bookkeeping of external +files for a format. Such external files can be used for +table of contents, list of figures, et cetera. +If the presence +of such objects is under the control of the user, we need some +general routines for opening and closing files, and keeping +track of what files we have opened at the user's request. + +Here only some routines for bookkeeping will be described. +Let us say there is a list of auxiliary files, and an auxiliary +counter: \begin{verbatim} +\newtoks\auxlist \newcount\auxcount +\end{verbatim} +First of all there must be an operation to add auxiliary files: +\begin{verbatim} +\def\NewAuxFile#1{\AddToAuxList{#1}% + % plus other actions + } +\def\AddToAuxList#1{\let\\=\relax + \edef\act{\noexpand\auxlist={\the\auxlist \\{#1}}}% + \act} +\end{verbatim} +This adds the name to the list in a uniform format: +\begin{verbatim} +\NewAuxFile{toc} \NewAuxFile{lof} +\showthe\auxlist +> \\{toc}\\{lof}. +\end{verbatim} +using the control sequence \verb>\\> which is left undefined. + +Now this control sequence can be used for instance to +count the number of elements in the list:\begin{verbatim} +\def\ComputeLengthOfAuxList{\auxcount=0 + \def\\##1{\advance\auxcount1\relax}% + \the\auxlist} +\ComputeLengthOfAuxList \showthe\auxcount +> 2. +\end{verbatim} +Another use of this structure is the following: +at the end of the job we can now close all auxiliary +files at once, by\begin{verbatim} +\def\CloseAuxFiles{\def\\##1{\CloseAuxFile{##1}}% + \the\auxlist} +\def\CloseAuxFile#1{\message{closing file: #1. }% + % plus other actions + } +\CloseAuxFiles +\end{verbatim} +which gives the output +\begin{verbatim} +closing file: toc. closing file: lof. +\end{verbatim} + +% \begin{comment} + +% %\spoint Dynamic macro definition +% \subsection{Dynamic macro definition} + +% Unpacking token lists inside an \cs{edef} can be put to a +% rather ambitious use: dynamic definition of macros. +% Consider a simple example. +% \altt +% We set ourselves the goal of letting +% the user define macros, without ever having to use \cs{def}. +% The syntax for this could look like\begin{verbatim} +% \startdefinition +% \do:this +% \do:that +% \define:MyMacro +% \end{verbatim} +% such that \verb>\show\MyMacro> gives \begin{verbatim} +% > \MyMacro=macro: +% ->\this \that . +% \end{verbatim} +% An implementation of this uses a token list to collect +% the commands that the user specifies:\begin{verbatim} +% \newtoks\actionlist +% \end{verbatim} +% The first command is easy:\begin{verbatim} +% \def\startdefinition{\actionlist{}} +% \end{verbatim} +% Now the \cs{do} command has to hang control sequences +% in the \cs{actionlist}:\begin{verbatim} +% \def\do:#1 {% +% \edef\act{\noexpand\appendaction +% \expandafter\noexpand\csname#1\endcsname}% +% \act} +% \end{verbatim} +% The \cs{edef} is used solely to form the actual control sequence. +% The next macro uses \cs{edef} to unpack the \cs{actionlist} so far: +% \begin{verbatim} +% \def\appendaction#1{% +% \edef\act{\noexpand\actionlist= +% {\the\actionlist \noexpand#1}}% +% \act} +% \end{verbatim} +% Finally, definition of the user macro also needs an \cs{edef}. +% Some \cs{expandafter} trickery is necessary here to form +% the control sequence of the user macro:\begin{verbatim} +% \def\define:#1 {% +% \expandafter\edef\csname#1\endcsname{\the\actionlist}} +% \end{verbatim} + +% Of course, this is a very simple, rather pointless, example. +% However, it illustrates an important principle of how +% token lists can be used to implement another syntax level +% in \TeX\ (see~\cite{EL}). This principle underlies the +% \term Lollipop\par +% `Lollipop' format that was used to typeset this book. + +% \end{comment} +%%%% end of input file [token] + +%\InputFile:baseline +%%%% this is input file [baseline] +%\subject[baseline] Baseline Distances +\endofchapter +\chapter{Baseline Distances}\label{baseline} + +\hbox{}\vfil\vfil\hbox{} +Lines of text are in most cases not of equal height or depth. +Therefore \TeX\ adds interline glue to keep baselines at a uniform +distance from one another. +This chapter treats the computation of such +interline glue. + +\begin{inventory} + +\item [\cs{baselineskip}] + The `ideal' baseline distance between neighbouring + boxes on a vertical list. Plain \TeX\ default:~\n{12pt}. + +\item [\cs{lineskiplimit}] + Distance to be maintained between the bottom and top of + neighbouring boxes on a vertical list. + Plain \TeX\ default:~\n{0pt}. + +\item [\cs{lineskip}] + Glue added if the distance between bottom + and top of neighbouring boxes + is less than \cs{lineskiplimit}. + Plain \TeX\ default:~\n{1pt}. + +\item [\cs{prevdepth}] + Depth of the last box added to a vertical list as it is + perceived by \TeX. + +\item [\cs{nointerlineskip}] + Macro to prevent interline glue insertion once. + +\item [\cs{offinterlineskip}] + Macro to prevent interline glue globally + henceforth. + +\item [\cs{openup}] + Increase \cs{baselineskip}, \cs{lineskip}, + and \cs{lineskiplimit} by specified amount. + +\end{inventory} + + +\hbox{}\vfil\hbox{} + +%\point Interline glue +\section{Interline glue} + +%\input figs17 +\message{fig17 missing} + +\TeX\ tries to keep a certain distance between the reference +\term glue !interline\par\term baseline! distance\par +points of boxes that are added to a vertical list; +in particular it tries to keep the baselines of ordinary text +at a constant distance, the \csidx{baselineskip}. Actually, +the \cs{baselineskip} is a \gr{glue}, so line distances can +stretch or shrink. However, the natural sizes, +as well as the stretch and the shrink, are the same +between all lines. + +When boxes, whether they are lines of a paragraph or explicit boxes, +are appended to a vertical list, glue +is added usually so that the depth of the preceding box +and the height of the current one add up to the \cs{baselineskip}. +This has the effect of keeping the reference points +of subsequent lines at regular intervals. + +\eject + +\message{fig one missing} +%\begin{disp}\leavevmode\hbox{}\nl\figone\end{disp} + +However, this process can bring the bottom and top of two +subsequent boxes to be less than \cs{lineskiplimit} apart: +\message{fig two missing} +%\begin{disp}\leavevmode\figtwo\end{disp} + +In that case, \cs{lineskip} glue is added: +\message{fig three missing} +%\begin{disp}\leavevmode\figthree\end{disp} +Note that this will usually increase the distance +between the baselines of the boxes to more than the +\cs{baselineskip}. + +The exact process is this: +\begin{itemize} +\item if \cs{prevdepth} is \n{-1000pt} or less, +no glue is added, otherwise +\item \TeX\ calculates the distance between the bottom of the previous box +and the top of the current one as the natural width of the +\cs{baselineskip} minus \cs{prev\-depth} (the +depth of the last box) and minus the height of the current box; +\item if this distance is at least \csidx{lineskiplimit}, +glue is added with the calculated distance as natural size, +and with the stretch and shrink of the \cs{baselineskip}, +\item otherwise \csidx{lineskip} glue is added. +\item \csidx{prevdepth} is set to the depth of the +current item. +\end{itemize} + +There are two exceptional situations: +no interline glue is added before and after a rule, +and the \cs{prevdepth} is not updated by an \cs{unvbox} +or \cs{unvcopy} command. After a rule interline glue +is prevented by a value of \n{-1000pt} of the \cs{prevdepth}. + +The above process is carried out, irrespective of what extra +glue may have been inserted in between the boxes. +Thus a skip in between boxes in vertical mode will not +affect the distance calculated from the baseline distances, +and therefore also not the amount of baselineskip glue. +The same holds for glue added with \cs{vadjust} inside +a paragraph. + +\begin{example}\begin{verbatim} +\baselineskip=10pt \lineskiplimit=2pt \lineskip=2pt +\setbox0=\vbox{\hbox{\vrule depth4pt} + \hbox{\vrule height 3pt}} +\showbox0 +\end{verbatim} +gives\begin{verbatim} +\box0= +\vbox(10.0+0.0)x0.4 +.\hbox(0.0+4.0)x0.4 +..\rule(*+4.0)x0.4 +.\glue(\baselineskip) 3.0 +.\hbox(3.0+0.0)x0.4 +..\rule(3.0+*)x0 +\end{verbatim} +Bringing the boxes to within \cs{lineskiplimit} +of each other, that is\begin{verbatim} +\setbox0\vbox{\hbox{\vrule depth4pt} + \hbox{\vrule height 5pt}} +\showbox0 +\end{verbatim} +gives\begin{verbatim} +\box0= +\vbox(11.0+0.0)x0.4 +.\hbox(0.0+4.0)x0.4 +..\rule(*+4.0)x0.4 +.\glue(\lineskip) 2.0 +.\hbox(5.0+0.0)x0.4 +..\rule(5.0+*)x0.4 +\end{verbatim} +where \cs{lineskip} glue has been inserted +instead of the usual \cs{baselineskip} glue. +\end{example} + +The plain \TeX\ default values are +\begin{verbatim} +\lineskiplimit=0pt lineskip=1pt +\end{verbatim} +so, when boxes start to touch each other, they are +moved one point apart. + +%\point The perceived depth of boxes +\section{The perceived depth of boxes} + +The decision process for interline glue uses \csidx{prevdepth} +as the perceived depth of the preceding box on the vertical +list. The \cs{prevdepth} parameter can be used only in +vertical mode. + +The \cs{prevdepth} is set to the depth of boxes added to the +vertical list, but it is not affected by \cs{unvbox} +or \cs{unvcopy}. After an \cs{hrule} it is set to +\n{-1000pt} to prevent interline glue before the next box. + +At the beginning of a vertical list \cs{prevdepth} +is set to \n{-1000pt}, except in an \cs{halign} +and \cs{noalign} code contained therein, where it +is carried over from the surrounding list. +At the end of the alignment the value of \cs{prevdepth} +set by the last alignment row is carried to the outer list. + +In order to prevent interline glue just once, all that +is needed is to alter the \cs{prevdepth}. +\cstoidx nointerlineskip\par +\begin{verbatim} +\def\nointerlineskip{\prevdepth=-1000pt} +\end{verbatim} + +The \csidx{offinterlineskip} macro is much more drastic: +it prevents {\sl all\/} interline glue from the moment +of its call onwards, or, if it is used inside a paragraph, +from the start of that paragraph. +Its definition is +\begin{verbatim} +\baselineskip=-1000pt \lineskip=0pt +\lineskiplimit\maxdimen +\end{verbatim} +where the second line is the essential one: it +causes \TeX\ to add \cs{lineskip} glue (which is zero) +always. +Settings for \cs{baselineskip} do not matter any more then. + +The \cs{offinterlineskip} macro has an important application +in alignments (see Chapter~\ref{align}). + +By setting \begin{verbatim} +\lineskiplimit=-\maxdimen +\end{verbatim} +you can force \TeX\ to apply the \cs{baselineskip} +always, regardless of whether this would bring boxes too close +together or, indeed, if this would make them overlap. + +%\point Terminology +\section{Terminology} + +In hot metal typesetting, all letters of a particular font +were on a `body' of the same +size. Thus every line of type had the same height and depth, and +the resulting distance between the baselines would be some suitable +value for that type. If for some reason this distance should +be larger (see~\cite{White:line} for a discussion of this), +strips of lead would be inserted. The extra distance was +called the `leading' (pronounced `ledding'). + +With phototypesetting, when the baseline distance was sometimes +called the `film transport', this terminology blurred, and the +term `leading' was also used for the baseline distance. Some of this +confusion is also present in \TeX: the parameter \cs{baselineskip} +specifies the baseline distance, but in the trace output +(see the examples above) the glue inserted to make the +baseline distance equal to \cs{baselineskip} is called +\cs{baselineskip}. + +%\point Additional remarks +\section{Additional remarks} + +In general, for documents longer than one page it is desirable +to have the same baseline distance throughout. However, +for one-page documents you may add stretchability to the +baselineskip, for instance if the text has to be flush bottom. + +Increasing the distance between just one pair of lines +can be done with \cs{vadjust}. The argument of this +command is vertical material that\vadjust{\kern2pt} +will be inserted in the +vertical list right after the line where this command was given. +The second line of this paragraph, for instance, +contains the command \verb-\vadjust{\kern2pt}-. + +The amount of leading cannot be changed in the middle of +a paragraph, because the value for \cs{baselineskip} +that is used is the one that +is current when the paragraph is finally broken and +added to the main vertical list. The same holds +for the \cs{lineskip} and \cs{lineskiplimit}. + +The plain \TeX\ macro \csidx{openup} +increases the \cs{baselineskip}, \cs{lineskip}, and +\cs{lineskiplimit} by the amount of the argument +to the macro. In effect, this increases line distances +by this amount regardless of whether they are governed +by \cs{baselineskip} or \cs{lineskip}. + + +%%%% end of input file [baseline] + +%\InputFile:par +%%%% this is input file [par] +%\subject[par:start] Paragraph Start +\endofchapter +\chapter{Paragraph Start}\label{par:start} + +At the start of a paragraph \TeX\ inserts a vertical skip +as a separation from the preceding paragraph, and a horizontal +skip as an indentation for the current paragraph. +This chapter explains the exact sequence +of actions, +and it discusses how \TeX's decisions can be altered. + +\begin{inventory} +\item [\cs{indent}] + Switch to horizontal mode and insert a box of width \cs{parindent}. + +\item [\cs{noindent}] + Switch to horizontal mode with an empty horizontal list. + +\item [\cs{parskip}] + Amount of glue added to + the surrounding vertical list when a paragraph starts. + Plain \TeX\ default:~\n{0pt plus 1pt}. + +\item [\cs{parindent}] + Size of the indentation box added in front of a paragraph. + Plain \TeX\ default:~\n{20pt}. + +\item [\cs{everypar}] + Token list inserted in front of paragraph text; + +\item [\cs{leavevmode}] + Macro to switch to horizontal mode if necessary. + +\end{inventory} + + +%\point When does a paragraph start +\section{When does a paragraph start} + +\TeX\ starts a paragraph whenever it switches from +vertical mode to (unrestricted) horizontal mode. This switch can +be effected by one of the commands +\cs{indent} and +\cs{noindent}, for example\begin{verbatim} +{\bf And now~\dots} +\vskip3pt +\noindent It's~\dots +\end{verbatim} +or by any \gram{horizontal command}. +Horizontal commands include characters, in-line formulas, +and horizontal skips, but not boxes. +Consider the following examples. +\alt +The character `I' is a horizontal command: +\begin{verbatim} +\vskip3pt +It's~\dots +\end{verbatim} +A single \n\$ is a horizontal command: +\begin{verbatim} +$x$ is supposed~\dots +\end{verbatim} +The control sequence \cs{hskip} is a horizontal command: +\begin{verbatim} +\hskip .5\hsize Long indentation~\dots +\end{verbatim} +The full list of horizontal commands is given on +page~\pageref{h:com:list}. + +Upon recognizing a horizontal command in vertical mode, +\TeX\ will perform an \cs{indent} command (and all the actions +associated with it; see below), +and after that it will reexamine the horizontal command, +this time executing it. + + + +%\point What happens when a paragraph starts +\section{What happens when a paragraph starts} + +The \csidx{indent} and \csidx{noindent} commands +\term paragraph! start\par +cause a paragraph to be started. +An~\cs{indent} command can either be placed explicitly by +the user or a macro, or it can be inserted by \TeX\ when +a \gr{horizontal command} occurs in vertical mode; +a~\cs{noindent} command can only be placed explicitly. + +After either command is encountered, +\csidx{parskip} glue is appended to the surrounding vertical +list +unless \TeX\ is in internal vertical mode +and that list is empty +(for example, at the start of a \cs{vbox} or \cs{vtop}). +\TeX\ then switches to unrestricted horizontal mode +with an empty horizontal list. +In the case of \cs{indent} (which may be inserted +implicitly) an empty \cs{hbox} of width +\cstoidx parindent\par +\cs{parindent} is placed at the start of the horizontal list; +after \cs{noindent} no indentation +box is inserted. + +The contents of the \csidx{everypar} \gr{token parameter} +are then inserted into the input (see some applications below). +After that, +the page builder is exercised (see Chapter~\ref{page:break}). +Note that this happens in horizontal mode: this is to +move the \cs{parskip} glue to the current page. + +If an \cs{indent} command is given while \TeX\ is already in +horizontal mode, the indentation box is inserted just the same. +This is not very useful. + +%\point Assorted remarks +\section{Assorted remarks} + +%\spoint Starting a paragraph with a box +\subsection{Starting a paragraph with a box} + +An \cs{hbox} does not imply horizontal mode, so +an attempt to start a paragraph with a box, for instance +\begin{verbatim} +\hbox to 0cm{\hss$\bullet$\hskip1em}Text .... +\end{verbatim} +will make the text following the box +wind up one line below the box. +It is necessary to switch to horizontal mode +explicitly, using for instance \cs{noindent} or +\cs{leavevmode}. +The latter is defined using \cs{unhbox}, +which is a horizontal command. + +%\spoint Starting a paragraph with a group +\subsection{Starting a paragraph with a group} + +If the first \gram{horizontal command} of a paragraph +is enclosed in braces, the \cs{everypar} is evaluated +inside the group. This may give unexpected results. +Consider this example: +\begin{verbatim} +\everypar={\setbox0=\vbox\bgroup\def\par{\egroup}} +{\bf Start} a paragraph ... \par +\end{verbatim} +The \gr{horizontal command} starting the paragraph is the +character~`S', so when \cs{everypar} has been inserted +the input is essentially +\begin{verbatim} +{\bf \indent\setbox0=\vbox\bgroup + \def\par{\egroup}Start} a paragraph ... \par +\end{verbatim} +which is equivalent to +\begin{verbatim} +{\bf \setbox0=\vbox{Start} a paragraph ... \par +\end{verbatim} +The effect of this is rather different from what was intended. +\alt +Also, \TeX\ will probably end the job inside a group. + +%\point Examples +\section{Examples} + +%\spoint Stretchable indentation +\subsection{Stretchable indentation } + +Considering that \cs{parindent} is a \gram{dimen}, not a \gram{glue}, +it is not possible to declare +\begin{verbatim} +\parindent=1cm plus 1fil +\end{verbatim} +in order to get +a variable indentation at the start of a paragraph. +This problem may be solved by putting +\begin{verbatim} +\everypar={\nobreak\hskip 1cm plus 1fil\relax} +\end{verbatim} +The \cs{nobreak} serves to prevent (in rare cases) a line break +at the stretchable glue. + +%\spoint Suppressing indentation +\subsection{Suppressing indentation} + +Inserting +\verb.{\setbox0=\lastbox}. in the horizontal list +at the beginning of the paragraph +removes the indentation: +indentation consists of a box, which is available through +\cs{lastbox}. Assigning it effectively removes it from the list. + +However, this command sequence +has to be inserted at a moment when \TeX\ has +already switched to horizontal mode, so explicit insertion +of these commands in front of the first \gram{horizontal +command} of the paragraph does not work. +The moment of insertion of the \cs{everypar} tokens +is a better candidate: specifying +\begin{verbatim} +\everypar={{\setbox0=\lastbox}} +\end{verbatim} +leads to unindented paragraphs, even if \cs{parindent} is +not zero. + + +%\spoint[indent:scheme] An indentation scheme +\subsection{An indentation scheme} +\label{indent:scheme} + +The above idea of letting the indentation box be removed +\howto Control indentation systematically\par +by \cs{everypar} can be put to use in a systematic approach +to indentation, where two conditionals +\begin{verbatim} +\newif\ifNeedIndent %as a rule +\newif\ifneedindent %special cases +\end{verbatim} +control whether paragraphs should indent as a rule, and +whether in special cases indentation is needed. +This section is taken from~\cite{E3}. + +We take a fixed \cs{everypar}: +\begin{verbatim} +\everypar={\ControlledIndentation} +\end{verbatim} +which executes in some cases the macro \cs{RemoveIndentation} +\begin{verbatim} +\def\RemoveIndentation{{\setbox0=\lastbox}} +\end{verbatim} +The implementation of \cs{ControlledIndentation} is:\begin{verbatim} +\def\ControlledIndentation + {\ifNeedIndent \ifneedindent + \else \RemoveIndentation\needindenttrue \fi + \else \ifneedindent \needindentfalse + \else \RemoveIndentation + \fi \fi} +\end{verbatim} +In order to regulate indentation for a whole document, +the user now once specifies, for instance, +\begin{verbatim} +\NeedIndenttrue +\end{verbatim} +to indicate that, in principle, +all paragraphs should indent. +Macros such as \cs{section} can then prevent +indentation in individual cases: +\begin{verbatim} +\def\section#1{ ... \needindentfalse} +\end{verbatim} + + +%\spoint[skip:scheme] A paragraph skip scheme +\subsection{A paragraph skip scheme} +\label{skip:scheme} + +The use of \cs{everypar} to control indentation, +\howto Control vertical white space systematically\par +as was sketched above, can be extended to the +paragraph skip. + +A visible white space between paragraphs can be +created by the \cs{parskip} parameter, but, once this +parameter has been set to some value, it is difficult +to prevent paragraph skip in certain places elegantly. +Usually, white space above and below environments +and section headings should be specifiable independently +of the paragraph skip. This section sketches an +approach where \cs{parskip} is set to zero directly +above and below certain constructs, while the \cs{everypar} +is used to restore former values. This section is +taken from~\cite{E4}. + +First of all, here are two tools. The control sequence +\cs{csarg} will be used only inside other macros; +a typical call will look like +\begin{verbatim} +\csarg\vskip{#1Parskip} +\end{verbatim} +Here is the definition:\begin{verbatim} +\def\csarg#1#2{\expandafter#1\csname#2\endcsname} +\end{verbatim} +Next follows a generalization of \cs{vskip}: the macro +\cs{vspace} will not place its argument if the previous glue item +is larger; otherwise it will eliminate the preceding +glue, and place its argument.\begin{verbatim} +\newskip\tempskipa +\def\vspace#1{\tempskipa=#1\relax + \ifvmode \ifdim\tempskipa<\lastskip + \else \vskip-\lastskip \vskip\tempskipa \fi + \else \vskip\tempskipa \fi} +\end{verbatim} + +Now assume that any construct \n{foo} +with surrounding white space +starts and ends with macro calls \verb>\StartEnvironment{foo}> and +\verb>\EndEnvironment{foo}> respectively. +Furthermore, assume that to this environment there correspond +three glue registers: +the \cs{fooStartskip} (glue +above the environment), \cs{fooParskip} (the paragraph skip +inside the environment), and the \cs{fooEndskip} (glue below +the environment). + +For restoring the value of the paragraph skip +a conditional and a glue register are needed:\begin{verbatim} +\newskip\TempParskip \newif\ifParskipNeedsRestoring +\end{verbatim} +The basic sequence for the +starting and ending macros for the environments is then +\begin{verbatim} +\TempParskip=\parskip\parskip=0cm\relax +\ParskipNeedsRestoringtrue +\end{verbatim} + +The implementations can now be given as:\begin{verbatim} +\def\StartEnvironment#1{\csarg\vspace{#1Startskip} + \begingroup % make changes local + \csarg\TempParskip{#1Parskip} \parskip=0cm\relax + \ParskipNeedsRestoringtrue} +\def\EndEnvironment#1{\csarg\vspace{#1Endskip} + \endgroup % restore global values + \ifParskipNeedsRestoring + \else \TempParskip=\parskip \parskip=0cm\relax + \ParskipNeedsRestoringtrue + \fi} +\end{verbatim} +The \cs{EndEnvironment} macro needs a little comment: +if an environment is used inside another one, and +it occurs before the first paragraph in that environment, +the value of the paragraph skip for the outer environment +has already been saved. Therefore no further actions are +required in that case. + +Note that both macros start with a vertical skip. This prevents +the \cs{begingroup} and \cs{endgroup} statements from +occurring in a paragraph. + +We now come to the main point: if necessary, the +\cs{everypar} will restore the value of the paragraph skip. +\begin{verbatim} +\everypar={\ControlledIndentation\ControlledParskip} +\def\ControlledParskip + {\ifParskipNeedsRestoring + \parskip=\TempParskip \ParskipNeedsRestoringfalse + \fi} +\end{verbatim} + +%\subject[par:end] Paragraph End +\endofchapter +\chapter{Paragraph End}\label{par:end} + +\TeX's mechanism for ending a paragraph is ingenious and effective. +This chapter explains the mechanism, the role of \cs{par} in it, +and it gives a number of practical remarks. + +\begin{inventory} +\item [\cs{par}] + Finish off a paragraph and go into vertical mode. + +\item [\cs{endgraf}] + Synonym for \cs{par}: \verb>\let\endgraf=\par> + +\item [\cs{parfillskip}] + Glue that is placed between the last + element of the paragraph and the line end. + Plain \TeX\ default:~\n{0pt plus 1fil}. +\end{inventory} + +%\point The way paragraphs end +\section{The way paragraphs end} + +A paragraph is terminated by the primitive \cs{par} command, +\term paragraph! end\par +which can +be explicitly typed by the user (or inserted by +a macro expansion):\begin{verbatim} +... last words.\par +A new paragraph ... +\end{verbatim} +It can be implicitly generated in the input processor of \TeX\ +by an empty line (see Chapter~\ref{mouth}):\begin{verbatim} +... last words. + +A new paragraph ... +\end{verbatim} +The \cs{par} can be inserted because a \gr{vertical command} +occurred in unrestricted horizontal mode:\begin{verbatim} +... last words.\vskip6pt +A new paragraph ... +\end{verbatim} +Also, a paragraph ends if a closing brace is found +in horizontal mode inside \cs{vbox}, \cs{insert}, or \cs{output}. + +After the \cs{par} command \TeX\ goes into vertical mode +and exercises the page builder (see page~\pageref{par:page:build}). +If the \cs{par} was inserted because a vertical command occurred in +horizontal mode, the vertical command is then examined anew. +The \cs{par} does not insert any vertical +glue or penalties itself. A~\cs{par} command also clears +the paragraph shape parameters (see Chapter~\ref{par:shape}). + +%\spoint The \cs{par} command and the \cs{par} token +\subsection{The \cs{par} command and the \cs{par} token} + +It is important to distinguish between the \cs{par} token +and the primitive \cs{par} command that is the initial meaning of +that token. The \cs{par} token is inserted when the input +processor sees an empty +line, or when the execution processor finds a \gram{vertical command} +in horizontal mode; +the \cs{par} command is what actually closes off a paragraph. +Decoupling the token and the command is an important tool +for special effects in paragraphs (see some examples in +Chapters \ref{boxes} and~\ref{rules}). + + +%\spoint Paragraph filling: \cs{parfillskip} +\subsection{Paragraph filling: \cs{parfillskip}} + +After the last element of the paragraph \TeX\ implicitly inserts +the equivalent of +\cstoidx parfillskip\par +\begin{verbatim} +\unskip \penalty10000 \hskip\parfillskip +\end{verbatim} +The \cs{unskip} serves to remove any spurious glue at the +paragraph end, such as the space generated by the +line end if the \cs{par} was inserted by the input processor. +For example:\message{check unsplit paragraph example} +\begin{verbatim} +end. + +\noindent Begin +\end{verbatim} +results in the tokens +\begin{disp}\n{end.\char32}\cs{par} \n{Begin}\end{disp} +With the sequence inserted by the \cs{par} this becomes +\begin{disp}\n{end.\char32}\verb>\unskip\penalty10000\hskip ...>\end{disp} +which in turn gives +\begin{disp}\verb>end.\penalty ...>\end{disp} + +The \cs{parfillskip} is in plain \TeX\ first-order infinite +(\n{0pt plus 1fil}), +so ending a paragraph with \verb.\hfil$\bullet$\par. +will give a bullet halfway between the last word and the +line end; with \verb.\hfill$\bullet$\par. it will be +flush right. + + +%\point Assorted remarks +\section{Assorted remarks} + +%\spoint Ending a paragraph and a group at the same time +\subsection{Ending a paragraph and a group at the same time} + +If a paragraph is set in a group, +it may be necessary to ensure that the \cs{par} ending +the paragraph occurs inside the group. +The parameters influencing the typesetting of the paragraph, +such as the \cs{leftskip} and the \cs{baselineskip}, +are only looked at when the paragraph is finished. +Thus finishing off a paragraph with +\begin{verbatim} +... last words.}\par +\end{verbatim} +causes the values to be used +that prevail outside the group, instead of those inside. + +Better ways to end the paragraph are +\begin{verbatim} +... last words.\par} +\end{verbatim} +or +\begin{verbatim} +... last words.\medskip} +\end{verbatim} +In the second example the vertical command \cs{medskip} +causes the \cs{par} token to be inserted. + +%\spoint Ending a paragraph with \cs{hfill}\cs{break} +\subsection{Ending a paragraph with \cs{hfill}\cs{break}} + +The sequence \verb.\hfill\break. is a way to force +a `newline' inside a paragraph. If you end a paragraph +with this, however, you will probably +get an \verb-Underfull \hbox- error. +Surprisingly, the underfull box is not the broken line +\ldash after all, that one was filled \rdash +but a completely empty box following it (actually, it +does contain the \cs{leftskip} and \cs{rightskip}). + +What happens? +The paragraph ends with \begin{verbatim} +\hfill\break\par +\end{verbatim} +which turns into +\begin{verbatim} +\hfill\break\unskip\nobreak\hskip\parfillskip +\end{verbatim} +The \cs{unskip} finds no preceding glue, so the \cs{break} +is followed by a penalty item and a glue item, both of +which disappear after the line break has been chosen at the +\cs{break}. +However, \TeX\ has already decided that there should be an extra +line, that is, an \verb.\hbox to \hsize.. And there is nothing +\alt +to fill it with, so an underfull box results. + +%\spoint Ending a paragraph with a rule +\subsection{Ending a paragraph with a rule} + +See page~\pageref{par:leaders:end} for paragraphs ending with +rule leaders instead of the default \cs{parfillskip} +white space. + +%\spoint No page breaks in between paragraphs +\subsection{No page breaks in between paragraphs} + +The \cs{par} command does not insert any glue in the +\howto Prevent page breaks in between paragraphs\par +vertical list, so +in the sequence +\begin{verbatim} + ... last words.\par \nobreak \medskip +\noindent First words ... +\end{verbatim} +no page breaks will occur between the paragraphs. +The vertical list generated is +\begin{verbatim} +\hbox(6.94444+0.0)x ... % last line of paragraph +\penalty 10000 % \nobreak +\glue 6.0 plus 2.0 minus 2.0 % \medskip +\glue(\parskip) 0.0 plus 1.0 % \parskip +\glue(\baselineskip) 5.05556 % interline glue +\hbox(6.94444+0.0)x ... % first line of paragraph +\end{verbatim} +\TeX\ will not break this vertical list above the \cs{medskip}, +because the penalty value prohibits it; it will not break +at any other place, because it can only break at glue if +that glue is preceded by a non-discardable item. + +%\spoint Finite \cs{parfillskip} +\subsection{Finite \cs{parfillskip}} + +In plain \TeX, \cs{parfillskip} has a (first-order) infinite +stretch component. All other glue in the last line of a +paragraph will then be set at natural width. +If the \cs{parfillskip} has only finite (or possibly zero) +stretch, other glue will be stretched or shrunk. +A display formula in a paragraph with such a last line +will be surrounded by \cs{abovedisplayskip} and \cs{belowdisplayskip}, +even if \cs{abovedisplayshortskip} glue would be in order. + +The reason for this is that glue setting is slightly +machine-dependent, and any such processes should be kept +out of \TeX's global decisions. + +%\spoint A precaution for paragraphs that do not indent +\subsection{A precaution for paragraphs that do not indent} + +If you are setting a text with both the paragraph indentation +and the white space between paragraphs zero, you run the risk +that the start of a new paragraph may be indiscernible when +the last line of the previous paragraph ends almost +or completely flush right. +A~sensible precaution for this is to set the \cs{parfillskip} +to, for instance \begin{verbatim} + \parfillskip=1cm plus 1fil +\end{verbatim} +instead of the usual \n{0cm~plus~1fil}. + +On the other hand, you may let yourself be convinced by +\cite{Tsch} that paragraphs should always indent. + +%\subject[par:shape] Paragraph Shape +\endofchapter +\chapter{Paragraph Shape}\label{par:shape} + +This chapter treats the parameters and commands that influence the +\term paragraph! shape\par +shape of a paragraph. + +\begin{inventory} +\item [\cs{parindent}] + Width of the indentation box added in front of a paragraph. + Plain \TeX\ default:~\n{20pt}. + +\item [\cs{hsize}] + Line width used for typesetting a paragraph. + Plain \TeX\ default:~\n{6.5in}. + +\item [\cs{leftskip}] + Glue that is placed to the left of all lines of a paragraph. + + +\item [\cs{rightskip}] + Glue that is placed to the right of all lines of a paragraph. + + +\item [\cs{hangindent}] + If positive, this indicates indentation from the left margin; + if negative, this is the negative of the indentation + from the right margin. + +\item [\cs{hangafter}] + If positive, this denotes the number of lines + before indenting starts; + if negative, the absolute value of this is the number + of indented lines starting with the first line of the paragraph. + Default:~\n1. + +\item [\cs{parshape}] + Command for general paragraph shapes. + +\end{inventory} + + +%\point The width of text lines +\section{The width of text lines} + +When \TeX\ has finished absorbing a paragraph, +\term line! width\par +it has formed a horizontal list, starting with an indentation +box, and ending with \cs{parfillskip} glue. +This list is then broken into lines of length \cs{hsize}. +\cstoidx hsize\par\cstoidx leftskip\par\cstoidx rightskip\par +Each line of a paragraph is padded left and right with +certain amounts of glue, the \cs{leftskip} and \cs{rightskip}, +which are taken into account in reaching \cs{hsize}. + +The values of \cs{leftskip} and \cs{rightskip} are taken +into account in the line-breaking algorithm. +Thus the main point about the \csidx{raggedright} +macro in plain \TeX\ and the \LaTeX\ `flushleft' +environment is that they +set the \cs{rightskip} to zero plus some stretch. + +The commands \cs{parshape} and \cs{hangindent} +also affect line width. They work by altering the +\cs{hsize} and afterwards shifting the boxes +containing the lines. + +%\point Shape parameters +\section{Shape parameters} + +%\spoint Hanging indentation +\subsection{Hanging indentation} + +\message{twolines?} +A simple, and frequently occurring, paragraph shape is that +\term hanging! indentation\par +\cstoidx hangafter\par\cstoidx hangindent\par +with a number of starting or trailing lines indented. +\TeX\ can realize such shapes using two parameters: +\cs{hangafter} and \cs{hangindent}. +Both can assume positive and negative values. + +The \cs{hangindent} controls the amount of indentation: +\begin{itemize}\item \cs{hangindent}${}>0$: the paragraph +is indented at the left margin by this amount. +\item\cs{hangindent}${}<0$: the paragraph is indented +at the right margin by the absolute value of this amount. +\end{itemize} +\def\exnul{\leftskip=0pt \rightskip=0pt \relax} +For example (assume \cs{parindent=0pt}), +\begin{disp}\leavevmode\message{Check parshape example!}% +\hbox{%\Distance:verbatimwhiteleft=0pt +$\vcenter{\snugbox{\begin{verbatim} + a a a a a a a a a a a a ... + + \hangindent=10pt + a a a a a a a a a a a a ... + + \hangindent=-10pt + a a a a a a a a a a a a ... +\end{verbatim} +}}$\quad gives\quad %\Spaces:2 gives \Spaces:2 +$\vcenter{\parindent0pt \setbox0\hbox{a a a a a}\hsize\wd0 + \leftskip=0pt %\parskip6pt + a a a a a a a a a a a a \dots\par%\vskip\baselineskip + \hangindent=10pt + a a a a a a a a a a a a \dots\par%\vskip\baselineskip + \hangindent=-10pt + a a a a a a a a a a a a \dots\par}$ +}\end{disp} +The default value of \cs{hangindent} is~\n{0pt}. + +The \cs{hangafter} parameter determines the number of +lines that is indented: +\begin{itemize}\item \cs{hangafter}${}\geq0$: +after this number of lines the rest of the lines will be +indented; in other words, this many lines from the +start of the paragraph will not be indented. +\item \cs{hangafter}${}<0$: the absolute value of this +is the number of lines that will be indented starting +at the beginning of the paragraph.\end{itemize} +For example, +\message{check left align} +\begin{disp}\leavevmode\hbox{%\Distance:verbatimwhiteleft=0pt +$\vcenter{\snugbox{\begin{verbatim} + a a a a a a a a a a a a ... + + \hangindent=10pt \hangafter=2 + a a a a a a a a a a a a ... + + \hangindent=10pt \hangafter=-2 + a a a a a a a a a a a a ... +\end{verbatim} +}}$%\quad looks like\quad% \Spaces:2 looks like \Spaces:2 +$\vcenter{\parindent0pt \setbox0\hbox{a a a a a}\hsize\wd0 + \leftskip=0pt %\parskip6pt + a a a a a a a a a a a a \dots\par%\vskip\baselineskip + \hangindent=10pt \hangafter=2 + a a a a a a a a a a a a \dots\par%\vskip\baselineskip + \hangindent=10pt \hangafter=-2 + a a a a a a a a a a a a \dots\par}$ +}\end{disp} +The default value for \cs{hangafter} is~\n1. + +With both parameters having the possibility to +be positive and negative, +four ways of hanging indentation result. See below +for hanging indentation into the margin (`outdent'). + +Hanging indentation is implemented as follows. +The amount of hanging indentation is subtracted +from the \cs{hsize} for the lines that indent; +after the paragraph has been broken into horizontal +boxes, the lines that should indent on the left are +shifted right. + +Regular indentation of size \cs{parindent} is not +influenced by hanging indentation. Thus you should +start a paragraph with hanging indentation +explicitly by~\cs{noindent} if the extra +indentation is unwanted. + +The default values of \cs{hangindent} and \cs{hangafter} are +restored after every \cs{par} command. + +%\spoint General paragraph shapes: \cs{parshape} +\subsection{General paragraph shapes: \cs{parshape}} + +Quite general paragraph shapes can be implemented +using \csidx{parshape}. With this command line lengths and indentation +for the first $n$ lines +of a paragraph can be specified. Thus this command +takes $2n+1$ parameters: the number of lines $n$, followed +by $n$ pairs of an indentation and a line length. +\begin{disp} \cs{parshape}\gr{equals} + $n$ $i_1$ $\ell_1$ $\ldots$ $i_n$ $\ell_n$\end{disp} +The specification for the last line is repeated if the +paragraph following has more than $n$ lines. If there are fewer +than $n$ lines the remaining specifications are ignored. +The default value is (naturally) \cs{parshape${}={}$0}. + +A \cs{parshape} command takes precedence over a \cs{hangindent} +if both have been specified. +%Regular \cs{parindent} indentation +%is suppressed if \cs{parshape} is in effect. +Regular \cs{parindent}, \cs{leftskip}, +and \cs{rightskip} are still obeyed if \cs{parshape} is in effect. + +The \cs{parshape} parameter is, like \cs{hangindent}, \cs{hangafter}, +and \cs{looseness} (see Chapter~\ref{line:break}), +cleared after a \cs{par} +command. Since every empty line generates a \cs{par} token, +one should not leave an empty line +between a paragraph shape (or hanging indentation) +declaration and the following paragraph. + +The control sequence +\alt +\cs{parshape} is an \gr{internal integer}: +its value is the number of lines $n$ with which +it was set. + +%\point Assorted remarks +\section{Assorted remarks} + +%\spoint Centred last lines +\subsection{Centred last lines} + +Equal stretch and shrink amounts for the \cs{leftskip} and +\cs{rightskip} +give centred texts, in the sense that each line is +centred. +For proper centring of the first +and last lines of a paragraph the \cs{parindent} and +\cs{parfillskip} have to be made zero. +However, the margins are ragged. + +A surprising application of \cs{leftskip} and \cs{rightskip} +\mdqon +\howto Centre the first/""last line of a paragraph\par +\mdqoff +leads to paragraphs with flush margins and a centred +last line. +\begin{verbatim} +\leftskip=0cm plus 0.5fil \rightskip=0cm plus -0.5fil +\parfillskip=0cm plus 1fil +\end{verbatim} + +For all lines of a paragraph but the +last one the stretch components +add up to zero so the \cs{leftskip} and \cs{rightskip} +inserted are zero. +On the last line the \cs{parfillskip} adds \hbox{\n{plus 1fil}} +of stretch; therefore there is a total of +\hbox{\n{plus 0.5fil}} of stretch at both the left and right +end of the line. + +It would have been incorrect to specify +\begin{verbatim} +\leftskip=0cm plus 0.5fil \rightskip=0cm minus 0.5fil +\end{verbatim} +\TeX\ gives an error about this: it complains about +`infinite shrinkage'. + +Centring not only the last line, but also the +first line of a paragraph can be done by +the parameter settings +\begin{verbatim} +\parindent=0pt \everypar{\hskip 0pt plus -1fil} +\leftskip=0pt plus .5fil +\rightskip=0pt plus -.5fil +\end{verbatim} +This time a horizontal skip inserted by \cs{everypar} +combines with the \cs{leftskip} to give the same +amount of stretchability on both sides of the +first line of the paragraph. + +%\spoint Indenting into the margin +\subsection{Indenting into the margin} + +Suppose you want a hanging indent of \n{1cm} {\sl into\/} +\howto Indent into the margin\par +the left margin after the first two lines of a paragraph. +Specifying \verb/\hangindent=-1cm/ will give +a hanging indentation of one centimetre from the {\sl right\/} +margin, so another approach is necessary. The following does the +job: +\begin{verbatim} + \leftskip=-1cm \hangindent=1cm \hangafter=-2 +\end{verbatim} +The only problem with this is that +the leftskip needs to be reset after the paragraph. +Suitable redefinition of \cs{par} removes this objection: +\begin{verbatim} +\def\hangintomargin{\bgroup + \leftskip=-1cm \hangindent=1cm \hangafter=-2 + \def\par{\endgraf\egroup}} +\end{verbatim} +The redefinition of \cs{par} is here local to the paragraph that +should be outdented. + +Another, elegant, solution uses \cs{parshape}: +\begin{verbatim} + +\dimen0=\hsize \advance\dimen0 by 1cm +\parshape=3 % three lines: + 0cm\hsize % first line specification + 0cm\hsize % second line specification + -1cm\dimen0 % third line specification +\end{verbatim} + +%\spoint Hang a paragraph from an object +\subsection{Hang a paragraph from an object} + +The \LaTeX\ format has a macro, \cs{@hangfrom}, to have +\howto Hang a paragraph from an object\par +one paragraph of text hanging from some object, usually a box +or a short line of text. + +\begingroup +\medskip +\def\hangobject{Example \ } +\setbox0=\hbox{\hangobject} +\hangindent \wd0 \noindent \hangobject +This paragraph is an example of the \cs{hangfrom} macro +defined below. +In the \LaTeX\ document +styles, the \cs{@hangfrom} macro (which is similar to this) +is used for multi-line section headings.\par +\endgroup + +Consider then the macro \cs{hangfrom}: +\begin{verbatim} + +\def\hangfrom#1{\def\hangobject{#1}\setbox0=\hbox{\hangobject}% + \hangindent \wd0 \noindent \hangobject \ignorespaces} +\end{verbatim} +Because of the default \cs{hangafter=1}, this +will produce one line of width \cs{hsize}, after which the +rest of the paragraph will be left indented by the width of the +\cs{hangobject}. + +%\spoint Another approach to hanging indentation +\subsection{Another approach to hanging indentation} + +Hanging indentation can also be attained by a combination +of shifting the left margin and outdenting. +Itemized lists can for instance be implemented in this manner: +\begin{verbatim} +\newdimen\listindent +\def\itemize{\begingroup + \advance\leftskip by \listindent + \parindent=-\listindent} +\def\stopitemize{\par\endgroup} +\def\item#1{\par\leavevmode + \hbox to \listindent{#1\hfil}\ignorespaces + } +\end{verbatim} +If an item should encompass more than one paragraph, the +implementation could be +\begin{verbatim} +\newdimen\listindent \newdimen\listparindent +\def\itemize{\begingroup + \advance\leftskip by \listindent + \parindent=\listparindent} +\def\stopitemize{\par\endgroup} +\def\item#1{\par\noindent + \hbox to 0cm{\kern-\listindent #1\hfil}\ignorespaces + } +\end{verbatim} + +\begin{example} +\begin{verbatim} +\itemize\item{1.}First item\par +Is two paragraphs long. +\item{2.}Second item.\stopitemize +\end{verbatim} +gives +\begin{disp} +\def\itemize{\begingroup + \advance\leftskip by \parindent + \parindent=1em\relax} +\def\stopitemize{\par\endgroup} +\def\item#1{\par\noindent + \hbox to 0cm{\kern-\parindent #1\hfil}\ignorespaces + } +\itemize\item{1.}First item\par +Is two paragraphs long. +\item{2.}Second item.\stopitemize +\end{disp} +\end{example} + +%\spoint Hanging indentation versus \cs{leftskip} shifting +\subsection{Hanging indentation versus \cs{leftskip} shifting} + +From the above examples it would seem that +hanging indentation and modifying the \cs{leftskip} and \cs{rightskip} +are interchangeable. They are, but only to a certain extent. +\altt + +Setting \cs{leftskip} to some positive value for a paragraph +means that the \cs{hsize} stays the same, but every line +starts with a glue item. Hanging indentation, on the other hand, +is implemented by decreasing the \cs{hsize} value for the +lines that hang, and shifting the finished +horizontal boxes horizontally in the surrounding vertical list. + +The difference between the two approaches becomes visible +mainly in the fact that display formulas are not shifted +when the \cs{leftskip} is altered. +See Chapter~\ref{rules} for an example showing how leaders +are affected by margin shifting. + +%\spoint More examples +\subsection{More examples} + +Some more examples of paragraph shapes (effected by +various means) can be found in~\cite{E1}. One example +from that article appears on page~\pageref{varioset}. + +%\subject[line:break] Line Breaking +\endofchapter +\chapter{Line Breaking}\label{line:break} + +This chapter treats line breaking and the concept of `badness' that \TeX\ +uses to decide how to break a paragraph into lines, +or where to break a page. +The various penalties contributing to the cost of line breaking +are treated here, as is hyphenation. +Page breaking is treated in Chapter~\ref{page:break}. + +\begin{inventory} +\item [\cs{penalty}] + Specify desirability of not breaking at this point. + +\item [\cs{linepenalty}] + Penalty value associated with each line break. + Plain \TeX\ default:~\n{10}. + +\item [\cs{hyphenpenalty}] + Penalty associated with break at a discretionary item + in the general case. + Plain \TeX\ default:~\n{50}. + +\item [\cs{exhyphenpenalty}] + Penalty for breaking a horizontal line at a discretionary + item in the special case where the prebreak text is empty. + Plain \TeX\ default:~\n{50}. + +\item [\cs{adjdemerits}] + Penalty for adjacent visually incompatible lines. + Plain \TeX\ default:~\n{10$\,$000}. + +\item [\cs{doublehyphendemerits}] + Penalty for consecutive lines ending with a hyphen. + Plain \TeX\ default:~\n{10$\,$000}. + +\item [\cs{finalhyphendemerits}] + Penalty added when the penultimate line of a + paragraph ends with a hyphen. + Plain \TeX\ default:~\n{5000}. + +\item [\cs{allowbreak}] + Macro for creating a breakpoint by inserting a + \cs{penalty0}. + +\item [\cs{pretolerance}] + Tolerance value for a paragraph without hyphenation. + Plain \TeX\ default:~\n{100}. + +\item [\cs{tolerance}] + Tolerance value for lines in a paragraph with hyphenation. + Plain \TeX\ default:~\n{200}. + +\item [\cs{emergencystretch}] + (\TeX3 only) + Assumed extra stretchability in lines of a paragraph. + +\item [\cs{looseness}] + Number of lines by which this paragraph has to be made longer + than it would be ideally. + +\item [\cs{prevgraf}] + The number of lines in the paragraph last + added to the vertical list. + +\item [\cs{discretionary}] + Specify the way a character sequence is split up at a line break. + +\item [\cs{-}] + Discretionary hyphen; this is + equivalent to \verb|\discretionary{-}{}{}|. + +\item [\cs{hyphenchar}] + Number of the hyphen character of a font. + +\item [\cs{defaulthyphenchar}] + Value of \cs{hyphenchar} when a font is loaded. + Plain \TeX\ default:~\n{`\cs{-}}. + +\item [\cs{uchyph}] + Positive to allow hyphenation of words starting with a capital + letter. + Plain \TeX\ default:~\n{1}. + +\item [\cs{lefthyphenmin}] + (\TeX3 only) + Minimal number of characters before a hyphenation. + Plain \TeX\ default:~\n{2}. + +\item [\cs{righthyphenmin}] + (\TeX3 only) + Minimum number of characters after a hyphenation. + Plain \TeX\ default:~\n{3}. + +\item [\cs{patterns}] + Define a list of hyphenation patterns for the current + value of \cs{language}; allowed only in \IniTeX. + +\item [\cs{hyphenation}] + Define hyphenation exceptions for the current value of \cs{language}. + +\item [\cs{language}] + Choose a set of hyphenation patterns and exceptions. + +\item [\cs{setlanguage}] + Reset the current language. + +\end{inventory} + + +%\point Paragraph break cost calculation +\section{Paragraph break cost calculation} + +A paragraph is broken such that the amount $d$ of {\em demerits\/} +associated with breaking it is minimized. +The total amount of demerits for a paragraph is the sum +of those for the individual lines, plus possibly some extra +penalties. Considering a paragraph as a whole instead of +breaking it on a line-by-line basis can lead to better +line breaking: \TeX\ can choose to take a slightly less beautiful +line in the beginning of the paragraph in order to avoid +bigger trouble later on. + +For each line demerits are calculated from the {\em badness\/}~$b$ +of stretching or shrinking the line to the break, and +the {\em penalty\/}~$p$ associated with the break. +The badness is not allowed to exceed a certain prescribed +tolerance. + +In addition to the demerits for breaking individual lines, +\TeX\ assigns demerits for the way lines combine; see below. + +The +\mdqon +implementation of \TeX's paragraph"-breaking algorithm +\mdqoff +is explained in~\cite{K:break}. + +%\spoint Badness +\subsection{Badness} + +From the ratio between the stretch or shrink present in a +\term badness! and line breaking\par\term line breaking!badness\par +line, and the actual stretch or shrink taken, +the `badness' of breaking a line at a certain point is calculated. +This badness is an important +factor in the process of line breaking. +See page~\pageref{bad:form} for the formula for badness. + +In this chapter +badness will only be discussed in the context of line breaking. +Badness is also computed when a vertical list is stretched +or shrunk (see Chapter~\ref{page:break}). + +The following terminology is used to describe badness: +\begin{description} \item [tight (3)] +is any line that has shrunk with a badness~$b\geq13$, +that is, by using at least one-half of its amount of shrink +(see page~\pageref{bad:form} for the computation). +\item [decent (2)] +is any line with a badness~$b\leq12$. +\item [loose (1)] +is any line that has stretched with a badness~$b\geq13$, +that is, by using at least one-half of its amount of stretch. +\item [very loose (0)] +is any line that has stretched with a badness~$b\geq100$, +that is, by using its full amount of stretch or more. Recall +that glue can stretch, but not shrink more than its +allowed amount. +\end{description} +The numbering is used in trace output (Chapter~\ref{trace}), and +it is also used in the following definition: +if the classifications of two adjacent lines differ by more than~1, +the lines are said to be {\em visually incompatible\/}. +See below for the \cs{adjdemerits} parameter associated with this. + +Overfull horizontal and vertical +boxes are passed unnoticed if their excess width +or height is less than \cs{hfuzz} or \cs{vfuzz} respectively; +they are not reported if the badness is less than +\cs{hbadness} or \cs{vbadness} (see Chapter~\ref{boxes}). + +%\spoint Penalties and other break locations +\subsection{Penalties and other break locations} + +Line breaks can occur at the following places in horizontal +\cstoidx penalty\par +\term lists !horizontal! breakpoints in\par +\term lists !horizontal! penalties in \par +lists: +\begin{enumerate} \item At a penalty. The penalty value is the +`aesthetic cost' of breaking the line at that place. +Negative penalties are considered as bonuses. +A~penalty of $10\,000$ or more inhibits, and a penalty +of $-10\,000$ or less forces, a~break. + +Putting more than one penalty +in a row is equivalent to putting just the one with the +minimal value, because that one is the best candidate for line breaking. + +Penalties in horizontal mode are inserted by the user (or a +user macro). The only exception is the \cs{nobreak} +inserted before the \cs{parfillskip} glue. + +\item At a glue, if it is not part of a math formula, and +if it is preceded by a non-discardable item (see Chapter~\ref{hvmode}). +There is no penalty associated with breaking at glue. + +The condition about the non-discardable precursor is necessary, +because otherwise breaking in between two pieces of glue would +be possible, which would cause ragged edges to the paragraph. + +\item At a kern, if it is not part of a math formula +and if it is followed by glue. +There is no penalty associated with breaking at a~kern. + +\item At a math-off, if that is followed by glue. +Since math-off +(and math-on) act as kerns (see Chapter~\ref{math}), +this is very much like the previous case. +There is no penalty associated with breaking at a~math-off. + +\item At a discretionary break. The penalty +is the \cs{hyphenpenalty} or the \cs{exhyphenpenalty}. +This is treated below. +\end{enumerate} + +Any discardable material following the break \ldash glue, kerns, +\mdqon +math-on/""off and penalties \rdash is discarded. If one considers +\mdqoff +a line break at glue (kern, math-on{/}off) to occur at the +front end of the glue item, this implies that that piece +of glue disappears in the break. + +%\spoint Demerits +\subsection{Demerits} + +From the badness of a line and the penalty, if any, the demerits +of the line are calculated. Let $l$ be the value of +\csidx{linepenalty}, $b$~the badness of the line, +$p$~the penalty at the break; then the demerits $d$ +\term demerits\par +are given by +\begin{disp}$\displaystyle d=\cases{(l+b)^2+p^2&if $0\leq p<10\,000$\cr + (l+b)^2-p^2&if $-10\,000<p<0$\cr + (l+b)^2 &if $p\leq-10\,000$\cr}$\end{disp} + +Both this formula and the one for the badness are described +\alt +in \cite{K:break} as `quite arbitrary', +but they have been shown to lead to +good results in practice. + +The demerits for a paragraph are the sum of the demerits for +the lines, plus \begin{itemize} +\item the \csidx{adjdemerits} for any two + adjacent lines that are not visually compatible (see above), +\item \csidx{doublehyphendemerits} for any two + consecutive lines ending with a hyphen, and the +\item \csidx{finalhyphendemerits} + if the penultimate line of a paragraph + ends with a hyphen.\end{itemize} + +At the start of a paragraph \TeX\ acts as if +there was a preceding line which was `decent'. +Therefore \cs{adjdemerits} will be added if the first +line is `very loose'. Also, the last line +of a paragraph is ordinarily also `decent' +\ldash all spaces are set at natural width +owing to the infinite stretch in the \cs{parfillskip} \rdash +so \cs{adjdemerits} are added if +the preceding line is `very loose'. + +Note that the penalties at which a line break +is chosen weigh about as heavily as the badness of +the line, so they can be relatively small. +However, the three extra demerit parameters +have to be of the order of the square of +penalties and badnesses to weigh equally heavily. + +%\spoint The number of lines of a paragraph +\subsection{The number of lines of a paragraph} + +After a paragraph has been completed (or partially +completed prior to a display), the variable \csidx{prevgraf} +records the number of lines in the paragraph. +By assigning to this variable \ldash and +because this is a \gr{special integer} +such an assignment is automatically global \rdash +\TeX's decision processes can be influenced. +This may be useful in combination with hanging indentation +or \cs{parshape} specifications (see Chapter~\ref{par:shape}). + +\mdqon +Some direct influence of the line"-breaking process +\mdqoff +on the resulting number of lines exists. One factor +is the \cs{linepenalty} which is included in the demerits +of each line. By increasing the line penalty \TeX\ can be +made to minimize the number of lines in a paragraph. + +Deviations from the optimal number of lines, that is, the +number of lines stemming from the optimal way of breaking a +paragraph into lines, can be forced by the user by means +of the \csidx{looseness} parameter. This parameter, which is +reset every time the shape parameters +are cleared (see Chapter~\ref{par:shape}), +indicates by how many lines the current +paragraph should be made longer than is optimal. A~negative +value of \cs{looseness} will attempt to make the paragraph shorter +by a number of lines that is the absolute value of the parameter. + +\TeX\ will still observe the values +of \cs{pretolerance} and \cs{tolerance} (see below) +when lengthening or shortening a paragraph under influence +of \cs{looseness}. +Therefore, +\TeX\ will only lengthen or shorten a paragraph for as far +as is possible without exceeding these parameters. + + +%\spoint[between:lines] Between the lines +\subsection{Between the lines} +\label{between:lines} + +\TeX's +paragraph mechanism packages lines into horizontal boxes +that are appended to the surrounding vertical list. +The resulting sequence of vertical items is then a +repeating sequence of +\begin{itemize}\item a box containing a line of text, +\item possibly migrated vertical material (see page~\pageref{migrate}), +\item a penalty item reflecting the cost of a page break + at that point, which is normally the \cs{interlinepenalty} + (see Chapter~\ref{page:break}), and +\item interline glue, which is calculated automatically + on basis of the \cs{prevdepth} (see Chapter~\ref{baseline}). +\end{itemize} + +%\point The process of breaking +\section{The process of breaking} + +\TeX\ tries to break paragraphs in such a way that +\term paragraph! breaking into lines\par +the badness of each line does not exceed a certain tolerance. +If there exists more than one solution to this, the one with +the fewest demerits is taken. + +By setting \csidx{tracingparagraphs} to a positive value, +\TeX\ can be made to report the calculations of the +paragraph mechanism in the log file. Some implementations of \TeX\ +may have this option disabled to make \TeX\ run faster. + +%\spoint Three passes +\subsection{Three passes} + +First an attempt is made to split the paragraph into lines +without hyphenating, that is, without inserting discretionary +hyphens. This attempt succeeds if none of the +lines has a badness exceeding \csidx{pretolerance}. + +Otherwise, a second pass is made, inserting discretionaries +and using \csidx{tolerance}. +If \cs{pretolerance} is negative, the first pass is omitted. + +\TeX\ can be made to make a third pass if the first and +second pass fail. +If \csidx{emergencystretch} is a positive dimension, +\TeX\ will assume this much extra stretchability +in each line when badness and demerits are calculated. +Thus solutions that only slightly exceeded the given +tolerances will now become feasible. +However, no glue of size \cs{emergencystretch} is +actually present, so underfull box messages +may still occur. + +%\spoint Tolerance values +\subsection{Tolerance values} + +How much +trouble \TeX\ will have typesetting a piece of text +depends partly on the tolerance value. +Therefore it is sensible to have some idea of +what badness values mean in visual terms. + +For lines that are stretched, the badness is +100 times the cube of the stretch ratio. +A~badness of 800 thus means that the stretch ratio +is~2. +If the space is, +\alt +as in the ten-point Computer Modern Font, +\begin{verbatim} +3.33pt plus 1.67pt minus 1.11pt +\end{verbatim} +a badness of 800 means that spaces have been stretched to +\begin{disp} \n{3.33pt}${}+2\times{}$\n{1.67pt}${}={}$\n{6.66pt}\end{disp} +that is, to exactly double their natural size. +It is up to you to decide whether this is too large. + +%\point Discretionaries +\section{Discretionaries} + +A discretionary item \verb-\discretionary{..}{..}{..}- +\term discretionary item\par\cstoidx discretionary\par +marks a place where a word can be broken. +Each of the three arguments is a \gr{general text} +(see Chapter~\ref{gramm}): +they are, in sequence, +\begin{itemize} \item the {\em pre-break\/} text, which is appended +to the part of the word before the break, +\item the {\em post-break\/} text, which is prepended to the part +of the word after the break, and +\item the {\em no-break\/} text, which is used if the word +is not broken at the discretionary item.\end{itemize} +For example: \verb>ab\discretionary{g}{h}{cd}ef> +is the word \hbox{\n{abcdef}}, but it can be hyphenated +\alt +with \n{abg} before the break and \n{hef} after. +Note that there is no automatic hyphen character. + +All three texts may contain any sorts of tokens, +but any primitive commands and macros +should expand to boxes, kerns, and characters. + +%\spoint Hyphens and discretionaries +\subsection{Hyphens and discretionaries} + +Internally, \TeX\ inserts the equivalent of +\cstoidx hyphenchar\par\term character !hyphen\par +\begin{verbatim} +\discretionary{\char\hyphenchar\font}{}{} +\end{verbatim} +at every place where a word can be broken. No +such discretionary is inserted if \verb>\hyphenchar\font> +is not in the range 0--255, or if its position in the +font is not filled. +When a font is loaded, its \cs{hyphenchar} value +is set to \csidx{defaulthyphenchar}. The \cs{hyphenchar} +value can be changed after this. + +In plain \TeX\ the \cs{defaulthyphenchar} has the value~\verb>`\->, so +for all fonts character~45 (the \ascii\ hyphen character) +is the hyphen sign, unless +it is specified otherwise. + +The primitive command \verb|\-| (called a `discretionary hyphen') +\csterm -\par\term discretionary hyphen\par +is equivalent to the above +\verb|\discretionary{\char\hyphenchar\font}{}{}|. +Breaking at such a discretionary, whether inserted implicitly +by \TeX\ or explicitly by the user, has +a cost of \csidx{hyphenpenalty}. + + +In unrestricted horizontal mode an empty discretionary +\cs{disc\-re\-tio\-na\-ry}\verb-{}{}{}- +is automatically inserted after characters +whose character code is the \cs{hyphenchar} value +of the font, thus enabling hyphenation at that point. +The penalty for breaking a line at +such a discretionary with an empty pre-break text +is \csidx{exhyphenpenalty}, that is, the `explicit hyphen' penalty. + +If a word contains +discretionary breaks, for instance +because of explicit hyphen characters, +\TeX\ will not consider it for further hyphenation. +People have solved the ensuing problems by tricks +such as +\howto Enable hyphenation of a word containing a hyphen\par +\begin{verbatim} +\def\={\penalty10000 \hskip0pt -\penalty0 \hskip0pt\relax} +... integro\=differential equations... +\end{verbatim} +The skips before and after the hyphen lead \TeX\ into +treating the first and second half of the +compound expression as separate words; the penalty +before the first skip inhibits breaking before the hyphen. + +%\spoint Examples of discretionaries +\subsection{Examples of discretionaries} + +Languages such as German or Dutch have words that change +\term languages\par +spelling when hyphenated (German: `\hbox{backen}' +becomes `\hbox{bak-ken}'; Dutch: `\hbox{autootje}' +becomes `\hbox{auto-tje}'). This problem can be solved +with \TeX's discretionaries. + +For instance, for German (this is inspired by~\cite{Partl}): +\begin{verbatim} +\catcode`\"=\active +\def"#1{\ifx#1k\discretionary{k-}{k}{ck}\fi} +\end{verbatim} +which enables the user to write \verb>ba"ken>. + +In Dutch there is a further problem which allows a nice +systematic solution. Umlaut characters (`trema' is the +Dutch term) should often +disappear in a break, for instance `\hbox{na"apen}' +hyphenates as `\hbox{na-apen}', and `\hbox{onbe"invloedbaar}' +hyphenates as `\hbox{onbe-invloedbaar}'. A solution +(inspired by~\cite{Babel}) is +\begin{verbatim} +\catcode`\"=\active +\def"#1{\ifx#1i\discretionary{-}{i}{\"\i}% + \else \discretionary{-}{#1}{\"#1}\fi} +\end{verbatim} +which enables the user to type \verb>na"apen> and +\verb>onbe"invloedbaar>. + +%\point Hyphenation +\section{Hyphenation} + +\TeX's hyphenation algorithm uses a list of patterns to +\term hyphenation\par +determine at what places a word that is a candidate for +hyphenation can be broken. +Those aspects of hyphenation connected with these +patterns are +treated in appendix~H of \TeXbook; +the method of generating hyphenation patterns automatically +is described in~\cite{Liang}. People have been known +to generate lists of patterns by hand; +see for instance~\cite{Vas:add}. Such hand-generated lists +may be superior to automatically generated lists. + +Here it will mainly be described how \TeX\ declares a word to +be a candidate for hyphenation. The problem here is +how to cope with punctuation and things such as quotation marks +that can be attached to a word. Also, {\em implicit kerns\/}, +that is, kerns inserted because of font information, +must be handled properly. + +%\spoint Start of a word +\subsection{Start of a word} + +\TeX\ starts at glue items (if they are not in math mode) +looking for a {\em starting letter\/} of a word: +a character with non-zero \cs{lccode}, or a ligature starting +\mdqon +with such a character (upper/""lowercase codes are explained +\mdqoff +on page~\pageref{uc/lc}). +Looking for this starting letter, +\TeX\ bypasses any implicit kerns, and +characters with zero \cs{lccode} (this includes, +for instance, punctuation and quotation marks), +or ligatures starting with +such a character. + +If no suitable starting letter turns up, that is, if +something is found that is not a character or ligature, +\TeX\ skips to the next glue, and starts this algorithm anew. +Otherwise a trial word is collected consisting of +all following characters with non-zero \cs{lccode} +from the same font as the starting letter, or ligatures consisting +completely of such characters. Implicit kerns are allowed +between the characters and ligatures. + +If the starting letter is from a font for which the value +of \cs{hyphenchar} is invalid, or for which this character +does not exist, hyphenation is abandoned for this word. +If the starting letter is an uppercase letter (that is, +it is not equal to its own \cs{lccode}), \TeX\ will +abandon hyphenation unless \csidx{uchyph} is positive. +The default value for this parameter is~1 in +plain \TeX, +implying that capitalized words are subject to hyphenation. + +%\spoint End of a word +\subsection{End of a word} + + +Following the trial word can be characters (from another +font, or with zero \cs{lccode}), ligatures or implicit kerns. +After these items, if any, must follow +\begin{itemize}\item glue or an explicit kern, +\item a penalty, +\item a whatsit, or +\item a \cs{mark}, \cs{insert}, or \cs{vadjust} item. +\end{itemize} +In particular, the word will not be hyphenated if it is +followed by a \begin{itemize}\item box, \item rule, \item math +formula, or \item discretionary item.\end{itemize} + +Since discretionaries are inserted after the \cs{hyphenchar} +of the font, occurrence of this character inhibits further +hyphenation. Also, placement of accents is implemented using +explicit kerns (see Chapter~\ref{char}), so any \cs{accent} +command is considered to be the end of a word, and inhibits +hyphenation of the word. + +%\spoint \TeX2 versus \TeX3 +\subsection{\TeX2 versus \TeX3} + +There is a noticeable difference in the treatment of +\term \TeX\ version 3\par +hyphenated fragments between \TeX2 and \TeX3. +\TeX2 insists that the part before the break should be +at least two characters, and the part after the break three +characters, long. +Typographically this is a sound decision: this way +there are no two-character pieces of a word stranded at the +end or beginning of the line. Both before and after the break +there are at least three characters. + +In \TeX3 two integer parameters have been introduced to control +the length of these fragments: +\csidx{lefthyphenmin} and \csidx{righthyphenmin}. These are +set to 2 and~3 respectively in the plain format for \TeX3. +If the sum of these two is 63 or more, all hyphenation is +suppressed. + +Another addition in \TeX3, +the possibility to have several sets of hyphenation patterns, +is treated below. + +%\spoint Patterns and exceptions +\subsection{Patterns and exceptions} + +The statements \begin{disp}\cs{patterns}\gr{general text}\nl +\csidx{hyphenation}\gr{general text}\end{disp} +are \gr{hyphenation assignment}s, which are +\gr{global assignment}s. +The \csidx{patterns} command, which specifies a list +of hyphenation patterns, is allowed only in \IniTeX\ +(see Chapter~\ref{TeXcomm}), +and all patterns must be specified before the first +paragraph is typeset. + +Hyphenation exceptions can be specified at any time +\howto Specify exceptional hyphenations\par +with statements such as +\begin{verbatim} +\hyphenation{oxy-mo-ron gar-goyle} +\end{verbatim} +which specify locations where a word may be hyphenated. +Subsequent \cs{hyphenation} statements are cumulative. + +In \TeX3 these statements are taken to hold for the +language that is the current value of the \cs{language} +parameter. + +%\point Switching hyphenation patterns +\section{Switching hyphenation patterns} + +When typesetting paragraphs, \TeX\ (version~3) can use several +\alt +\term language\par +sets of patterns and hyphenation exceptions, for at most 256 +languages. + +If a \cs{patterns} or \cs{hyphenation} +command is given (see above), \TeX\ stores the patterns or exceptions +under the current value of the \csidx{language} parameter. +The \cs{patterns} command is only allowed in \IniTeX, and +patterns must be specified before any typesetting is done. +Hyphenation exceptions, however, can +be specified cumulatively, and not only in \IniTeX. + +In addition to the \cs{language} parameter, +\term language !current\par +which can be set by the user, \TeX\ has internally a `current +language'. This is set to zero at the start of every paragraph. +For every character that is added to a paragraph +the current language is compared with the value of \cs{language}, +and if they differ a whatsit element is added to the horizontal +list, resetting the current language to the value of \cs{language}. + +At the start of a paragraph, this whatsit is inserted +\altt +after the \cs{everypar} tokens, but \cs{lastbox} +can still access the indentation box. + +As an example, suppose that a format has been created such that +language~0 is English, and language~1 is Dutch. English hyphenations +will then be used if the user does not specify otherwise; +if a job starts with \begin{verbatim} +\language=1 +\end{verbatim} +the whole document +will be set using Dutch hyphenations, because \TeX\ will insert +a command changing the current language at the start of +every paragraph. For example: +\begin{verbatim} +\language=1 +T... +\end{verbatim} +gives +\begin{verbatim} +.\hbox(0.0+0.0)x20.0 % indentation +.\setlanguage1 (hyphenmin 2,3) % language whatsit +.\tenrm T % start of text +\end{verbatim} + +The whatsit can be inserted explicitly, without changing +the value of \csidx{language}, by specifying +\begin{disp}\cs{setlanguage}\gr{number}\end{disp} +However, this will hardly ever be needed. +One case where it may be necessary is when the contents of +a horizontal box are unboxed to a paragraph: inside the box no +whatsits are added automatically, since inside such a box +no hyphenation can take place. +See page~\pageref{wide:vbox} for another problem with text +in horizontal boxes. + +%%%% end of input file [par] + +%\InputFile:space +%%%% this is input file [space] +%\subject[space] Spacing +\endofchapter +\chapter{Spacing}\label{space} + +The usual interword space in \TeX\ is specified in the +\term spacing\par +font information, but the user can override this. +This chapter explains the rules by which +\TeX\ calculates interword space. + +\begin{inventory} + +\item [\cs{\char32}] + Control space. + Insert the same amount of space as a space token would + if \cs{spacefactor}${}=1000$. + +\item [\cs{spaceskip}] + Interword glue if non-zero. + +\item [\cs{xspaceskip}] + Interword glue if non-zero and \cs{spacefactor}${}\geq2000$. + +\item [\cs{spacefactor}] + 1000 times the ratio by which the stretch (shrink) component of the + interword glue should be multiplied (divided). + +\item [\cs{sfcode}] + Value for \cs{spacefactor} associated with a character. + +\item [\cs{frenchspacing}] + Macro to switch off extra space after punctuation. + +\item [\cs{nonfrenchspacing}] + Macro to switch on extra space after punctuation. + +\end{inventory} + + +\section{Introduction} + +In between words in a text, \TeX\ inserts space. This space has a +natural component, plus stretch and shrink to make justified +(right-aligned) text possible. Now, in certain styles of typesetting, +there is more space after punctuation. This chapter discusses the +mechanism that \TeX\ uses to realize such effect. + +Here is the general idea: +\begin{itemize} +\item After every character token, the \cs{spacefactor} quantity is + updated with the space factor code of that character. +\item When space is inserted, its natural size can be augmented + (if \cs{spacefactor}${}\geq2000$), and in general its stretch is + multiplied, and its shrink divided, by \cs{spacefactor}${}/1000$. +\item There are further rules, for instance so that in \n{...word.) + And...} the space is modified according to the period, not the + closing parenthesis. +\end{itemize} + +%\point Automatic interword space +\section{Automatic interword space} + + +For every space token in horizontal mode the interword glue +of the current font +is inserted, with stretch and shrink components, all +determined by \cs{fontdimen} parameters. +To be specific, font dimension~2 is the normal interword space, +dimension~3 is the amount of stretch of the interword +space, and 4~is the amount of shrink. Font dimension +7 is called the `extra space'; see below (the list +of all the font dimensions appears on page~\pageref{font:dims}). + +Ordinarily all spaces between words (in one font) would be treated +the same. To allow for differently sized spaces \ldash for instance +a typeset equivalent of the double spacing after +punctuation in typewritten documents \rdash +\term space! factor\par +\TeX\ associates with each character a so-called `space factor'. + +When a character is added to the current horizontal list, +the space factor code (\csidx{sfcode}) +of that character +is assigned to the space factor \csidx{spacefactor}. +There are two exceptions to this rule: +\begin{itemize} +\item When the space factor code is zero, the \cs{spacefactor} does + not change. This mechanism allows space factors to persist through + parentheses and such; see section~\ref{sec:sf-through-paren}. +\item When the space factor code of the last character is ${>}1000$ + and the current space factor is ${<}1000$, the space factor + becomes~1000. This mechanism prevents elongated spaces after + initials; see section~\ref{sec:sf-punct}. +\end{itemize} +The maximum space factor is~$32\,767$. + +The stretch component of the interword space is +multiplied by the space factor divided by 1000; +the shrink component is divided by this factor. +The extra space (font dimension~7) is +added to the natural component of the +interword space when the space factor is~${}\geq2000$. + +%\point User interword space +\section{User interword space} + +The user can override the interword space contained in +the \cs{fontdimen} parameters +by setting the +\csidx{spaceskip} and the \csidx{xspaceskip} to non-zero values. +If \cs{spaceskip} is non-zero, it is taken instead +of the normal interword space +(\cs{fontdimen2} plus \cs{fontdimen3} minus \cs{fontdimen4}), but +a non-zero \cs{xspaceskip} is used as interword space if +the space factor is~${}\geq2000$. + +If the \cs{spaceskip} is used, +its stretch and shrink components are +multiplied and divided respectively by \cs{spacefactor}$/1000$. + +Note that, if \cs{spaceskip} and \cs{xspaceskip} are +defined in terms of \n{em}, they change with the font. + +\begin{example} Let the following macros be given: +\begin{verbatim} +\def\a.{\vrule height10pt width4pt\spacefactor=1000\relax} +\def\b.{\vrule height10pt width4pt\spacefactor=3000\relax} +\def\c{\vrule height10pt width4pt\relax} +\end{verbatim} + then + +%\begin{disp}\leavevmode\PopIndentLevel + +\hbox{% +$\vcenter{\snugbox{% +\begin{verbatim} +\vbox{ +\fontdimen2\font=4pt % normal space +\fontdimen7\font=3pt % extra space +\a. \b. \c\par +% zero extra space +\fontdimen7\font=0pt +\a. \b. \c\par +% set \spaceskip for normal space +\spaceskip=2\fontdimen2\font +\a. \b. \c\par +% set \xspaceskip +\xspaceskip=2pt +\a. \b. \c\par +} +\end{verbatim} +}}$% +% +\quad gives\quad +% +\message{Check snug and drop!}% +$\vcenter{\snugbox{\parindent0pt\parskip=0pt +\def\a.{\vrule height10pt width4pt\spacefactor=1000\relax} +\def\b.{\vrule height10pt width4pt\spacefactor=3000\relax} +\def\c{\vrule height10pt width4pt\relax} +\leavevmode\strut\par\hbox{}\hbox{} +% set the normal space and extra space +\fontdimen2\font=4pt \fontdimen7\font=3pt +\a. \b. \c\par \vskip2\baselineskip +% zero extra space +\fontdimen7\font=0pt +\a. \b. \c\par \vskip2\baselineskip +% set \spaceskip for normal space +\spaceskip=2\fontdimen2\font +\a. \b. \c\par \vskip2\baselineskip +% set \xspaceskip +\xspaceskip=2pt +\a. \b. \c\par \leavevmode\strut +}}$% +% +} +%\end{disp} + +In all of these lines the glue is set at natural width. In the first +line the high space factor value after \cs{b} causes the extra +space \cs{fontdimen7} to be added. If this is zero (second line), the +only difference between space factor values is the stretch/shrink +ratio. In the third line the \cs{spaceskip} is taken +for all space factor values. If the \cs{xspaceskip} is nonzero, +it is taken (fourth line) instead of the \cs{spaceskip} +for the high value of the space factor. +\end{example} + +%\point[tie] Control space and tie +\section{Control space and tie} +\label{tie} + +Control space, \csc{\char32}, is a horizontal command +which inserts a space, +\term control! space\par\term space !control~--\par\csidx{\char32} +acting as if the current space factor is~1000. +However, it does not affect the value of \cs{spacefactor}. + +Control space has two main uses. First, it is convenient to use after +a control sequence: \verb+\TeX\ is fun!+ +Secondly, it can be used after abbreviations when \cs{nonfrenchspacing} +(see below) is in effect. For example: +\begin{verbatim} +\hbox spread 9pt{\nonfrenchspacing + The Reverend Dr. Drofnats} +\end{verbatim} +gives +\begin{disp} \hbadness=10000 \leavevmode +\hbox spread 9pt{\nonfrenchspacing + The Reverend Dr. Drofnats}\end{disp} +while +\begin{verbatim} +\hbox spread 9pt{\nonfrenchspacing + The Reverend Dr.\ Drofnats} +\end{verbatim} +gives +\begin{disp} \hbadness=10000 \leavevmode +\hbox spread 9pt{\nonfrenchspacing + The Reverend Dr.\ Drofnats}\end{disp} +(The \n{spread 9pt} is used to make the effect more visible.) + +The active character (in the plain format) tilde,~\n{\char126}, +\term tie\par\term ~@\char126\par +uses control space: it is defined as +\begin{verbatim} +\catcode`\~=\active +\def~{\penalty10000\ } +\end{verbatim} +Such an active tilde is called a `tie'; it inserts an ordinary +amount of space, and prohibits breaking at this space. + + +%\point More on the space factor +\section{More on the space factor} + +%\spoint Space factor assignments +\subsection{Space factor assignments} + +The space factor of a particular character can be assigned as +\term spacefactor code\par\cstoidx sfcode\par +\begin{disp}\cs{sfcode}\gr{8-bit number}\gr{equals}\gr{number}\end{disp} + +\IniTeX\ assigns a space factor code of 1000 to all characters +\label{ini:sf}% +except uppercase characters; they get a space factor code of~999. +The plain format then assigns space factor codes greater than +1000 to various punctuation symbols, for instance +\verb-\sfcode`\.=3000-, which triples the stretch and shrink +after a full stop. Also, for all space factor values $\geq2000$ +the extra space is added; see above. + +%\spoint Punctuation +\subsection{Punctuation} +\label{sec:sf-punct} + +Because the space factor cannot jump from a value below 1000 +to one above, a punctuation symbol after an uppercase +character will not have the effect on the interword space +that punctuation after a lowercase character has. + +\begin{example}\begin{verbatim} +a% \sfcode`a=1000, space factor becomes 1000 +.% \sfcode`.=3000, spacefactor becomes 3000 + % subsequent spaces will be increased. + +A% \sfcode`A=999, space factor becomes 999 +.% \sfcode`.=3000, space factor becomes 1000 + % subsequent spaces will not be increased. +\end{verbatim} +\end{example} + +Thus, initials +are not mistaken for sentence ends. +If an uppercase character does end a sentence, for instance +\begin{verbatim} +... and NASA. +\end{verbatim} +there are several solutions: +\begin{verbatim} +... NASA\spacefactor=1000. +\end{verbatim} +or +\begin{verbatim} +... NASA\hbox{}. +\end{verbatim} +which abuses the fact that after +a box the space factor is set to~1000. +The \LaTeX\ macro \cs{@} is equivalent to the first +possibility. + +In the plain format two macros are defined that switch between +\term frenchspacing\par\cstoidx frenchspacing\par +\cstoidx nonfrenchspacing\par +uniform interword spacing and extra space after punctuation. +The macro \cs{frenchspacing} sets the space factor code +of all punctuation to~1000; the macro \cs{nonfrenchspacing} +sets it to values greater than~1000. + +Here are the actual definitions from \n{plain.tex}:\begin{verbatim} +\def\frenchspacing{\sfcode`\.\@m \sfcode`\?\@m + \sfcode`\!\@m \sfcode`\:\@m + \sfcode`\;\@m \sfcode`\,\@m} +\def\nonfrenchspacing{\sfcode`\.3000 \sfcode`\?3000 + \sfcode`\!3000 \sfcode`\:2000 + \sfcode`\;1500 \sfcode`\,1250 } +\end{verbatim} +where \begin{verbatim} +\mathchardef\@m=1000 +\end{verbatim} +is given in the plain format. + +French spacing is a somewhat controversial issue: +\TeXbook\ acts as if non-French spacing +is standard practice in printing, but for instance in~\cite{Hart} +one finds `The space of the line should be used after +all points in normal text'. +Extra space after punctuation +may be considered a `typewriter habit', but this is +not entirely true. It used to be a lot more common +than it is nowadays, and there are rational arguments +against it: the full stop (point, period) at the end of a +sentence, where extra punctuation is most visible, +is rather small, so it carries some extra visual space + of its own above it. This book does not use extra space +after punctuation. + +%\spoint Other non-letters +\subsection{Other non-letters} +\label{sec:sf-through-paren} + +The zero value of the space factor code makes +characters that are not a letter and not punctuation +`transparent' for the space factor. + +\message{check break after Example} +\begin{example}\begin{verbatim} +a% \sfcode`a=1000, space factor becomes 1000 +.% \sfcode`.=3000, spacefactor becomes 3000 + % subsequent spaces will be increased. + +a% \sfcode`a=1000, space factor becomes 1000 +.% \sfcode`.=3000, space factor becomes 3000 +)% \sfcode`)=0, space factor stays 3000 + % subsequent spaces will be increased. +\end{verbatim} +\end{example} + +%\spoint Other influences on the space factor +\subsection{Other influences on the space factor} + +The space factor is 1000 when \TeX\ starts forming a +horizontal list, in particular after \cs{indent}, \cs{noindent}, +and directly after a display. It is also 1000 after +a \cs{vrule}, an accent, or a \gr{box} (in horizontal mode), but +it is not influenced by \cs{unhbox} or \cs{unhcopy} +commands. + +In the first column of a \cs{valign} the space factor of +the surrounding horizontal list is carried over; similarly, +after a vertical alignment the space factor is set to the +value reached in the last column. + +%%%% end of input file [space] + +%\InputFile:math +%%%% this is input file [math] +%\subject[mathchar] Characters in Math Mode +\endofchapter +\chapter{Characters in Math Mode}\label{mathchar} + +In math mode every character specifies by its +\cs{mathcode} what position of +a font to access, among other things. +For delimiters this story is a bit +more complicated. This chapter explains the concept +of math codes, and shows how \TeX\ implements variable +size delimiters. + +\begin{inventory} +\item [\cs{mathcode}] + Code of a character determining its treatment in math mode. + +\item [\cs{mathchar}] + Explicit denotation of a mathematical character. + +\item [\cs{mathchardef}] + Define a control sequence to be a synonym for + a~math character code. + +\item [\cs{delcode}] + Code specifying how a character should be used as delimiter. + +\item [\cs{delimiter}] + Explicit denotation of a delimiter. + +\item [\cs{delimiterfactor}] + 1000 times the fraction of a delimited formula that should be + covered by a delimiter. + Plain \TeX\ default:~\n{901} + +\item [\cs{delimitershortfall}] + Size of the part of a delimited formula that is allowed + to go uncovered by a delimiter. + Plain \TeX\ default:~\n{5pt} + +\item [\cs{nulldelimiterspace}] + Width taken for empty delimiters. + Plain \TeX\ default:~\n{1.2pt} + +\item [\cs{left}] + Use the following character as an open delimiter. + +\item [\cs{right}] + Use the following character as a closing delimiter. + +\item [\cs{big}] + One line high delimiter. + +\item [\cs{Big}] + One and a half line high delimiter. + +\item [\cs{bigg}] + Two lines high delimiter. + +\item [\cs{Bigg}] + Two and a half lines high delimiter. + +\item [\cs{bigl {\MainFont etc.}}] + Left delimiters. + +\item [\cs{bigm {\MainFont etc.}}] + Delimiters used as binary relations. + +\item [\cs{bigr {\MainFont etc.}}] + Right delimiters. + +\item [\cs{radical}] + Command for setting things such as root signs. + +\item [\cs{mathaccent}] + Place an accent in math mode. + +\item [\cs{skewchar}] + Font position of an after-placed accent. + +\item [\cs{defaultskewchar}] + Value of \cs{skewchar} when a font is loaded. + +\item [\cs{skew}] + Macro to shift accents on top of characters explicitly. + +\item [\cs{widehat}] + Hat accent that can + accommodate wide expressions. + +\item [\cs{widetilde}] + Tilde accent that can + accommodate wide expressions. + +\end{inventory} + +%\point Mathematical characters +\section{Mathematical characters} + +Each of the 256 permissible character codes has +\term math characters\par +an associated \csidx{mathcode}, which can be assigned by +\begin{disp}\cs{mathcode}\gr{8-bit number}\gr{equals}\gr{15-bit number}\end{disp} +When processing in math mode, \TeX\ replaces all characters of +categories 11 and~12, and \cs{char} and \cs{chardef} characters, +by their associated mathcode. + +The 15-bit math code is most conveniently denoted hexadecimally +as \verb-"xyzz-, where\begin{disp} +\n x${}\leq7$ is the class (see page~\pageref{math:class}),\nl +\n y is the font family number \alt +(see Chapter~\ref{mathfont}), and \nl +\n{zz} is the position of the character in the font.\end{disp} + +Math codes can also be specified directly by +\cstoidx mathchar\par\cstoidx mathchardef\par +a \gr{math character}, which can be\label{math:character} +\begin{itemize}\item\cs{mathchar}\gr{15-bit number}; +\item \gr{mathchardef token}, a control sequence that was defined by +\begin{disp}\cs{mathchardef}\gr{control sequence}\gr{equals}\gr{15-bit number} +\end{disp} + or +\item a delimiter command\alt +\begin{disp}\cs{delimiter}\gr{27-bit number}\end{disp} + where the last 12 bits +are discarded.\end{itemize} +The commands \cs{mathchar} and \cs{mathchardef} +are analogous to \cs{char} and \cs{char\-def} in text mode. +Delimiters are treated below. +A~\gr{mathchardef token} +can be used as a \gr{number}, even outside math mode. + +In \IniTeX\ all letters receive \cs{mathcode} \verb-"71zz- and +all digits receive \verb-"70zz-, where \verb-"zz- is the +hexadecimal position of the character in the font. +Thus, letters are initially from family~1 +(math italic in plain \TeX), and digits are from family~0 +(roman). +For all other characters, \IniTeX\ assigns +\begin{disp}\cs{mathcode}$\,x=x$,\end{disp} +thereby placing them also in family~0. + +If the mathcode is \verb-"8000-, +\label{mcode:8000}the smallest integer that is +not a \gr{15-bit number}, the character is treated as an active +character with the original character code. Plain \TeX\ +assigns a \cs{mathcode} of \verb-"8000- to the space, underscore and prime. + + +%\point Delimiters +\section{Delimiters} + +After \csidx{left} and \csidx{right} +\term delimiters\par +commands \TeX\ looks for a delimiter. A~delimiter +is either an explicit \cs{delimiter} command (or a +macro abbreviation for it), or a character with a non-zero +delimiter code. + +The \cs{left} and \cs{right} commands +implicitly delimit a group, which is considered as a subformula. +Since the enclosed formula can +be arbitrarily large, the quest for the proper delimiter is +a complicated story of looking at variants in two different +fonts, linked chains of variants in a font, and building +extendable delimiters from repeatable pieces. + +The fact that a group enclosed in \verb>\left...\right> is +treated as an independent subformula implies that a +sub- or superscript at the start of this formula is +not considered to belong to the delimiter. +For example, \TeX\ acts as if +\verb>\left(_2> is equivalent to \verb>\left({}_2>. +(A~subscript after a \cs{right} delimiter is positioned +with respect to that delimiter.) + +%\spoint[delcodes] Delimiter codes +\subsection{Delimiter codes } +\label{delcodes} + +To each character code there corresponds a delimiter +\cstoidx delcode\par\term delimiter codes\par +code, assigned by +\begin{disp}\cs{delcode}\gr{8-bit number}\gr{equals}% + \gr{24-bit number}\end{disp} +A delimiter code thus consists of six hexadecimal digits +\verb-"uvvxyy-, where\begin{disp} +\n{uvv} is the small variant of the delimiter, and\nl +\n{xyy} is the large variant;\nl +\n u, \n x are the font families of the variants, and\nl +\n{vv}, \n{yy} are the locations in those fonts.\end{disp} +Delimiter codes are used after \cs{left} and \cs{right} +commands. +\IniTeX\ sets all delimiter codes to~$-1$, +except\label{ini:del} +\verb-\delcode`.=0-, which makes the period an empty delimiter. +In plain \TeX\ delimiters have typically \n{u}${}=2$ and~\n{x}${}=3$, +that is, first family~2 is tried, and if no big +enough delimiter turns up family~3 is tried. + + +%\spoint Explicit \cs{delimiter} commands +\subsection{Explicit \cs{delimiter} commands} + +Delimiters can also be denoted +\cstoidx delimiter\par +explicitly by a \gr{27-bit number}, +\begin{verbatim} +\delimiter"tuvvxyy +\end{verbatim} +where \n{uvvxyy} are the small and large variant of the +delimiter as above; +the extra digit \n{t} (which is~$<8$) denotes the class +(see page~\pageref{math:class}). +For instance, the \cs{langle} macro is defined as +\begin{verbatim} +\def\langle{\delimiter "426830A } +\end{verbatim} +which means it belongs to class~4, opening. Similarly, +\cs{rangle} is of class~5, closing; and \cs{uparrow} is of class~3, +relation. + +After \cs{left} and \cs{right} \ldash that is, when \TeX\ +is looking for a delimiter \rdash the class digit is ignored; +otherwise \ldash when \TeX\ is not looking for a delimiter \rdash +the rightmost three digits are ignored, and the +four remaining digits are treated as a~\cs{mathchar}; see above. + +%\spoint[successor] Finding a delimiter; successors +\subsection{Finding a delimiter; successors} +\label{successor} + +Typesetting a delimiter is a somewhat involved affair. +\term delimiter sizes\par\term successors\par +First \TeX\ determines the size $y$ of the formula to be covered, +which is twice the maximum of the height and depth of the +formula. Thus the formula may not look optimal if +it is not centred itself. + +The size of the delimiter should be at least +\csidx{delimiterfactor}${}\times y/1000$ and at least +$y-{}$\csidx{delimitershortfall}. +\TeX\ then tries first the small variant, and if that one +is not satisfactory (or if the \n{uvv} part of the delimiter +is~\n{000}) it tries the large variant. If trying the large variant +does not meet with success, \TeX\ takes the largest delimiter +encountered in this search; if no delimiter at all was found +(which can happen if the \n{xyy} part is +\altt +also~\n{000}), +an empty box of width~\csidx{nulldelimiterspace} is taken. + +Investigating a variant means, in sequence, +\begin{itemize} \item if the current style (see page~\pageref{math:styles}) +is scriptscriptstyle +the \cs{scriptscriptfont} of the family is tried; +\item if the current style is scriptstyle or smaller +the \cs{scriptfont} of the family is tried; +\item otherwise the \cs{textfont} of the family is tried.\end{itemize} +The plain format puts the \verb-cmex10- font in all three +\term extension fonts\par +styles of family~3. + +Looking for a delimiter at a certain position in a certain font +means\begin{itemize}\item if the character is large enough, accept it; +\item if the character is extendable, accept it; +\item otherwise, if the character has a successor, that is, it is +part of a chain of increasingly bigger delimiters in the same +font, try the successor.\end{itemize} +Information about successors and extensibility of a delimiter +is coded in the font metric file of the font. +An extendable character has a top, a bottom, possibly a mid piece, +and a piece which is repeated directly below the top piece, and +directly above the bottom piece if there is a mid piece. + + +%\spoint \cs{big}, \cs{Big}, \cs{bigg}, and \cs{Bigg} +\subsection{\cs{big}, \cs{Big}, \cs{bigg}, and \cs{Bigg} +delimiter macros} + +In order to be able to use a delimiter outside the +\verb-\left...\right- context, or to specify a delimiter of +a different size than \TeX\ would have chosen, +four macros for `big' delimiters exist: \cs{big}, +\cs{Big}, \cs{bigg}, and \cs{Bigg}. These can be used with +anything that can follow \cs{left} or \cs{right}. + +Twelve further macros (for instance \cs{bigl}, \cs{bigm}, +\cstoidx big \rm etc.\par +%\csterm big \Style:roman etc.\par +and~\cs{bigr}) force such delimiters in the context of +an opening symbol, a binary relation, and a closing symbol +respectively:\begin{verbatim} +\def\bigl{\mathopen\big} +\def\bigm{\mathrel\big} \def\bigr{\mathclose\big} +\end{verbatim} + +The `big' macros themselves put the requested delimiter and +a null delimiter around an empty vertical box: +\begin{verbatim} +\def\big#1{{\nulldelimiterspace=0pt \mathsurround=0pt + \hbox{$\left#1\vbox to 8.5pt{}\right.$}}} +\end{verbatim} +As an approximate measure, +the \n{Big} delimiters are one and a half times as large (11.5pt) as +\n{big} delimiters; \n{bigg} ones are twice (14.5pt), and \n{Bigg} +ones are two and a half times as large (17.5pt). + +%\point Radicals +\section{Radicals} + +A radical is a compound of a left delimiter and an overlined +math expression. +\term radicals\par\cstoidx radical\par +The overlined expression is set in the +cramped version of the surrounding style +\alt +(see page~\pageref{math:styles}). + +In the plain format and the Computer Modern +math fonts there is only one radical: the square root +construct \begin{verbatim} +\def\sqrt{\radical"270370 } +\end{verbatim} +The control sequence \cs{radical} is followed by a \gr{24-bit number} +which specifies a small and a large variant of the left delimiter +as was explained above. Joining the delimiter and the rule +is done by letting the delimiter have a large depth, and a height +which is equal to the desired rule thickness. The rule can then +be placed on the current baseline. After the delimiter and the +ruled expression have been joined the whole is shifted +vertically to achieve the usual vertical centring +(see Chapter~\ref{math}). + +%\point Math accents +\section{Math accents} + +Accents in math mode are specified by +\cstoidx mathaccent\par\term accents in math mode\par +\begin{disp}\cs{mathaccent}\gr{15-bit number}\gr{math field}\end{disp} +Representing the 15-bit number as \verb>"xyzz>, +only the family~\n{y} and the character position~\n{zz} +are used: an accented expression acts as \cs{mathord} expression +(see Chapter~\ref{math}). + +In math mode whole expressions can be accented, +\alt +whereas in text mode only characters can be accented. +Thus in math mode accents can be stacked. However, the top +accent may (or, more likely, will) not be properly positioned +horizontally. Therefore the plain format has a macro \csidx{skew} +that effectively shifts the top accent. Its definition is +\begin{verbatim} +\def\skew#1#2#3{{#2{#3\mkern#1mu}\mkern-#1mu}{}} +\end{verbatim} +and it is used for instance like +\begin{verbatim} +$\skew4\hat{\hat x}$ +\end{verbatim} +\message{skew thing.} +%which gives~{\font\tmp=cmmi10 $\textfont\VMIfam=\tmp\skew4\hat{\hat x}$}. +which gives~{$\skew4\hat{\hat x}$}. + +For the correct positioning of accents over single characters +the symbol and extension font have a \csidx{skewchar}: +this is the largest accent that adds to the width of an +accented character. Positioning of any accent +is based on the width of the character to be accented, +followed by the skew character. + +The skew characters of the Computer Modern +math italic and symbol fonts are character \n{\hex7F}, +\alt +`$\mathchar"7F$',\message{skew characters} +and \n{\hex30}, `$\mathchar"30$', respectively. The \csidx{defaultskewchar} +value is assigned to the \cs{skewchar} when a font is loaded. +In plain \TeX\ this is~\n{-1}, so fonts ordinarily have no +\cs{skewchar}. + +Math accents can adapt themselves to the size of the accented +expression: \TeX\ will look for a successor of an accent +in the same way that it looks for a successor of a delimiter. +In the Computer Modern math fonts this mechanism is used in +\cstoidx widehat\par\cstoidx widetilde\par +the \cs{widehat} and \cs{widetilde} macros. +For example, +\begin{disp}\verb>\widehat x>, \verb>\widehat{xy}>, \verb>\widehat{xyz}> +\end{disp} give +\begin{disp}$\widehat x$, $\widehat{xy}$, $\widehat{xyz}$ +\end{disp} respectively. + + + + +%\subject[mathfont] Fonts in Formulas +\endofchapter +\chapter{Fonts in Formulas}\label{mathfont} + +For math typesetting a single current font is not sufficient, as it +is for text typesetting. Instead \TeX\ uses several font families, +and each family can contain three fonts. This chapter +explains how font families are organized, and how \TeX\ determines +from what families characters should be taken. + + +\begin{inventory} + +\item [\cs{fam}] + The number of the current font family. + +\item [\cs{newfam}] + Allocate a new math font family. + +\item [\cs{textfont}] + Access the textstyle font of a family.\alt + +\item [\cs{scriptfont}] + Access the scriptstyle font of a family.\alt + +\item [\cs{scriptscriptfont}] + Access the scriptscriptstyle font of a family.\alt + +\end{inventory} + +%\point Determining the font of a character in math mode +\section{Determining the font of a character in math mode} + +The characters in math formulas can be taken from several +\term font families\par +different fonts (or better, font families) without any user +commands. For instance, in plain \TeX\ math formulas use +the roman font, the math italic font, +the symbol font and the math extension font. + +In order to determine from which font a character is to be +taken, \TeX\ considers for each character in a formula its +\cs{mathcode} (this is treated in Chapter~\ref{mathchar}). +A~\cs{mathcode} is a 15-bit number of the form +\verb."xyzz., where the hex digits +have the following meaning:\begin{disp} +\n x:~class,\nl +\n y:~family,\nl +\n{zz}:~position in font.\end{disp} + +In general only the family determines from what font +a character is to be taken. +The class of a math character is mostly used to +control spacing and other aspects of typesetting. +Typical classes include `relation', `operator', `delimiter'. + +Class~7 is special in this respect: +it is called `variable family'. +If a character has a \cs{mathcode} of the form \verb."7yzz. +it is taken from family \n{y}, +unless the parameter \cs{fam} has a value in the range 0--15; +then it is taken from family~\cs{fam}. + + +%\point Initial family settings +\section{Initial family settings} + +Both lowercase and uppercase letters +are defined by \IniTeX\ to have math codes \verb>"71zz>, +\label{ini:fam}% +which means that they are of variable family, initially from +family~1. +As \TeX\ sets \verb.fam=-1., that is, +an invalid value, when a formula starts, +characters are indeed taken from +family~1, which in plain \TeX\ is math italic. + +Digits have math code \verb>"70zz> so they are initially from +family~0, in plain \TeX\ the roman font. +All other character codes have a mathcode +assigned by \IniTeX\ as +\begin{disp}\cs{mathcode}$\,x=x$\end{disp} which puts them in class~0, +ordinary, and family~0, roman in plain \TeX. + +In plain \TeX, commands such as \cs{sl} then set both a font and +a family: +\begin{verbatim} +\def\sl{\fam\slfam\tensl} +\end{verbatim} +so putting \cs{sl} in a formula will cause all letters, digits, +and uppercase Greek characters, to change to +slanted style. + +In most cases, any font can be assigned to any family, but +two families in \TeX\ have a special meaning: these are +families 2 and~3. +For instance, their number of \cs{fontdimen} parameters +is different from the usual~7. Family~2 needs 22 parameters, +and family~3 needs~13. These parameters have all a very +specialized meaning for positioning in math typesetting. +Their meaning is explained below, but for the full story +the reader is referred to appendix~G of \TeXbook. + + +%\point Family definition +\section{Family definition} + +\TeX\ can access 16 families of fonts in math mode; +font families have numbers 0--15. +The number of the +current family is recorded in the parameter~\csidx{fam}. + +The macro \csidx{newfam} gives the number of an unused family. +This number is assigned using \cs{chardef} to the control sequence. + + +Each font family can have a font meant for text style, script style, +and scriptscript style. Below it is explained how \TeX\ +determines in what style a (sub-) formula is to be typeset. + +Fonts are assigned to a family +\cstoidx textfont\par\cstoidx scriptfont\par\cstoidx scriptscriptfont\par +as follows: +\begin{verbatim} +\newfam\MyFam +\textfont\MyFam=\tfont \scriptfont\MyFam=\sfont +\scriptscriptfont\MyFam=\ssfont +\end{verbatim} +for the text, script, and scriptscript fonts of a family. +In general it is not necessary to fill all three members +of a family (but it is for family~3). +If \TeX\ needs a character from a family member +that has not been filled, +it uses the \cs{nullfont} instead, +a~primitive font that has no characters (nor a \n{.tfm} file). + + +%\point Some specific font changes +\section{Some specific font changes} + +%\spoint Change the font of ordinary characters and uppercase Greek +\subsection{Change the font of ordinary characters and uppercase Greek} + +All letters and the uppercase Greek characters are +by default in plain \TeX\ of class~7, +variable family, so changing \cs{fam} will change the font +from which they are taken. +For example +\begin{verbatim} +{\fam=9 x} +\end{verbatim} + gives an \n{x} from family~9. + +Uppercase Greek characters are defined by +\cs{mathchardef} statements in the plain format as \verb>"70zz>, +that is, variable family, initially roman. +Therefore, uppercase Greek character also change with the family. + +%\spoint Change uppercase Greek independent of text font +\subsection{Change uppercase Greek independent of text font} + +In the Computer Modern font layout, uppercase Greek letters +are part of the roman font; see page~\pageref{cmr:table}. +\alt +Therefore, introducing another +text font (with another layout) +will change the uppercase Greek characters +(or even make them disappear). +One way of remedying this is by introducing a new family in +which the \n{cmr} font, which contains the uppercase Greek, +resides. +The control sequences accessing these characters then have +to be redefined: +\begin{verbatim} +\newfam\Kgreek +\textfont\Kgreek=cmr10 ... +\def\hex#1{\ifcase#10\or 1\or 2\or 3\or 4\or 5\or 6\or + 7\or 8\or 9\or A\or B\or C\or D\or E\or F\fi} +\mathchardef\Gamma="0\hex\Kgreek00 % was: "0100 +\mathchardef\Beta ="0\hex\Kgreek01 % was: "0101 +\mathchardef\Gamma ... +\end{verbatim} +Note, by the way, +the absence of a either a space or a \cs{relax} token after +\n{\#1} in the definition of \cs{hex}. This implies that this +macro can only be called with an argument that is a +control sequence. + +%\spoint Change the font of lowercase Greek +\subsection{Change the font of lowercase Greek } + and mathematical symbols + +Lowercase Greek characters have math code +\verb>"01zz>, meaning they are always from the math italic family. +In order to change this one might redefine them, +for instance \verb.\mathchardef\alpha="710B., +to make them variable family. +This is not done in plain \TeX, because the Computer Modern +roman font does not +have Greek lowercase, although it does have the uppercase characters. + +Another way is to redefine them like \verb.\mathchardef\alpha="0n0B. +where \n{n} is the (hexadecimal) number of a family +compatible with math italic, containing for instance a bold +math italic font. + + +%\point Assorted remarks +\section{Assorted remarks} + +%\spoint New fonts in formulas +\subsection{New fonts in formulas} + +There are two ways to access a font inside mathematics. +\howto Change fonts in a math formula\par +\mdqon +After \cs{font}""\cs{newfont=....} it is not possible to get +\mdqoff +the `a' of the new font by \verb-$...{\newfont a}...$- +because \TeX\ does not look at the current font in math mode. +What does work is +\begin{verbatim} +$ ... \hbox{\newfont a} ...$ +\end{verbatim} +but this precludes the use of the new font in script and +scriptscript styles. + +The proper solution takes a bit more work: +\begin{verbatim} +\font\newtextfont=... +\font\newscriptfont=... \font\newsscriptfont=... +\newfam\newfontfam +\textfont\newfontfam=\newtextfont +\scriptfont\newfontfam=\newscriptfont +\scriptscriptfont\newfontfam=\newsscriptfont +\def\newfont{\newtextfont \fam=\newfontfam} +\end{verbatim} +after which the font can be used as +\begin{verbatim} +$... {\newfont a_{b_c}} ...$ +\end{verbatim} +in all three styles. + +%\spoint Evaluating the families +\subsection{Evaluating the families} + +\TeX\ will only look at what is actually in the \cs{textfont} +et cetera of the various families at the end of the whole +formula. Switching fonts in the families is thus not possible +inside a single formula. +The number of 16 families may therefore turn out to be restrictive +for some applications. + + +%\subject[math] Mathematics Typesetting +\endofchapter +\chapter{Mathematics Typesetting}\label{math} + +\TeX\ has two math modes, display and non-display, and +four styles, display, text, script, and scriptscript style, and +\altt +every object in math mode belongs to one of eight classes. +This chapter treats these concepts. + + + +\begin{inventory} +\item [\cs{everymath}] + Token list inserted at the start of a non-display formula. + +\item [\cs{everydisplay}] + Token list inserted at the start of a display formula. + +\item [\cs{displaystyle}] + Select the display style of mathematics typesetting. + +\item [\cs{textstyle}] + Select the text style of mathematics typesetting. + +\item [\cs{scriptstyle}] + Select the script style of mathematics typesetting. + +\item [\cs{scriptscriptstyle}] + Select the scriptscript style of mathematics typesetting. + +\item [\cs{mathchoice}] + Give four variants of a formula for the four styles + of mathematics typesetting. + +\item [\cs{mathord}] + Let the following character or subformula function + as an ordinary object. + +\item [\cs{mathop}] + Let the following character or subformula function + as a large operator. + +\item [\cs{mathbin}] + Let the following character or subformula function + as a binary operation. + +\item [\cs{mathrel}] + Let the following character or subformula function as a relation. + +\item [\cs{mathopen}] + Let the following character or subformula function + as a opening symbol. + +\item [\cs{mathclose}] + Let the following character or subformula function + as a closing symbol. + +\item [\cs{mathpunct}] + Let the following character or subformula function + as a punctuation symbol. + +\item [\cs{mathinner}] + Let the following character or subformula function + as an inner formula. + +\item [\cs{mathaccent}] + Place an accent in math mode. + +\item [\cs{vcenter}] + Construct a vertical box, vertically centred + on the math axis. + +\item [\cs{limits}] + Place limits over and under a large operator. + +\item [\cs{nolimits}] + Place limits of a large operator as subscript and + superscript expressions. + +\item [\cs{displaylimits}] + Restore default placement for limits. + +\item [\cs{scriptspace}] + Extra space after subscripts and superscripts. + Plain \TeX\ default:~\n{0.5pt} + +\item [\cs{nonscript}] + Cancel the next glue item if it occurs in + scriptstyle or scriptscriptstyle. + +\item [\cs{mkern}] + Insert a kern measured in mu units. + +\item [\cs{mskip}] + Insert glue measured in mu units. + +\item [\cs{muskip}] + Prefix for skips measured in mu units. + +\item [\cs{muskipdef}] + Define a control sequence to be a synonym for + a~\cs{muskip} register. + +\item [\cs{newmuskip}] + Allocate a new muskip register. + +\item [\cs{thinmuskip}] + Small amount of mu glue. + +\item [\cs{medmuskip}] + Medium amount of mu glue. + +\item [\cs{thickmuskip}] + Large amount of mu glue. + +\item [\cs{mathsurround}] + Kern amount placed before and after in-line formulas. + +\item [\cs{over}] + Fraction. + +\item [\cs{atop}] + Place objects over one another. + +\item [\cs{above}] + Fraction with specified bar width. + +\item [\cs{overwithdelims}] + Fraction with delimiters. + +\item [\cs{atopwithdelims}] + Place objects over one another with delimiters. + +\item [\cs{abovewithdelims}] + Generalized fraction with delimiters. + +\item [\cs{underline}] + Underline the following \gr{math symbol} or group. + +\item [\cs{overline}] + Overline the following \gr{math symbol} or group. + + +\item [\cs{relpenalty}] + Penalty for breaking after a binary relation + not enclosed in a subformula. + Plain \TeX\ default:~\n{500} + +\item [\cs{binoppenalty}] + Penalty for breaking after a binary operator not enclosed in + a subformula. + Plain \TeX\ default:~\n{700} + +\item [\cs{allowbreak}] + Macro for creating a breakpoint. + +\end{inventory} + +%\point[math:modes] Math modes +\section{Math modes} +\label{math:modes} + +\TeX\ changes to math mode when it encounters a math shift +\term math modes\par\term math shift character\par +character, category~3, in the input. After such an opening +math shift it investigates (without expansion) the next +token to see whether this is another math shift. +In the latter case \TeX\ starts processing in display math mode +until a closing double math shift is encountered: +\begin{disp}\verb> .. $$ >{\italic displayed formula}\verb> $$ ..>\end{disp} +Otherwise it starts processing an in-line formula +in non-display math mode: +\begin{disp}\verb> .. $ >{\italic in-line formula}\verb> $ ..>\end{disp} +The single math shift character is a \gr{horizontal command}. + +Exception: displays are not possible in restricted horizontal +mode, so inside an \cs{hbox} the sequence +\verb>$$> is an empty math formula and +not the start of a displayed formula. + +Associated with the two math modes are two \gr{token parameter} +registers (see also Chapter~\ref{token}): +at the start of an in-line formula the \csidx{everymath} tokens +are inserted; at the start of a displayed formula the +\cs{everydisplay} tokens are inserted. +Display math is treated further in the next chapter. + +Math modes can be tested for: \cs{ifmmode} is true +in display and non-display math mode, and \cs{ifinner} +is true in non-display mode, but not in display mode. + +%\point[math:styles] Styles in math mode +\section{Styles in math mode} +\label{math:styles} + +Math formulas are set in any of eight styles: +\term math styles\par +\begin{description} \item [D] +display style, \item [T] +text style, \item [S] +script style, \item [SS] +scriptscript style, +\end{description} +and the four `cramped' variants $D'$, $T'$, $S'$, $SS'$ of +\term cramped styles\par +these. The cramped styles differ mainly in the +fact that superscripts are not raised as far as in +the original styles. + +%\spoint Superscripts and subscripts +\subsection{Superscripts and subscripts} + +\TeX\ can typeset a symbol or group +\term superscript\par\term subscript\par +as a superscript (or subscript) to the preceding +symbol or group, if that preceding item +does not already have a superscript +(subscript). Superscripts (subscripts) are specified by +the syntax +\begin{disp}\gr{superscript}\gr{math field}\end{disp} +or +\begin{disp}\gr{subscript}\gr{math field}\end{disp} +where a \gr{superscript} (\gr{subscript}) is either a character +of category~7 (8), or a control sequence \cs{let} to such +a character. +The plain format has the control +\cstoidx\char94\par\cstoidx\char95\par +sequences +\begin{verbatim} +\let\sp=^ \let\sb=_ +\end{verbatim} +as implicit superscript +and subscript characters. + +Specifying a superscript (subscript) expression as the first +item in an empty math list is equivalent to specifying +it as the superscript (subscript) of an empty expression. +For instance, \begin{disp} +\verb>$^{...}>\quad is equivalent to\quad \verb>${}^{...}>\end{disp} + +For \TeX's internal calculations, superscript and subscript +expressions are made wider by \csidx{scriptspace}; +the value of this in plain \TeX\ is~\n{0.5pt}. + +%\spoint Choice of styles +\subsection{Choice of styles} + +Ordering the four styles $D$, $T$, $S$, and~$SS$, and +considering the other four as mere variants, the +style rules for math mode are as follows: +\begin{itemize}\item In any style superscripts and subscripts +are taken from the next smaller style. Exception: +in display style they are taken in script style. +\item Subscripts are always in the cramped variant of +the style; superscripts are only cramped if the original +style was cramped. +\item In an \verb-{..\over..}- formula in any style +the numerator and denominator are taken from the next +smaller style. +\item The denominator is always in cramped style; +the numerator is only in cramped style if the original +style was cramped. +\item Formulas under a \cs{sqrt} or \cs{overline} +are in cramped style.\end{itemize} + +Styles can be forced by the explicit commands +\alt +\cstoidx displaystyle\par\cstoidx textstyle\par +\cstoidx scriptstyle\par\cstoidx scriptscriptstyle\par +\cs{displaystyle}, \cs{textstyle}, \cs{scriptstyle}, +and~\cs{scriptscriptstyle}. + + +In display style and text style the \cs{textfont} of the +current family is used, +in scriptstyle the \cs{scriptfont} is used, and in +\alt +scriptscriptstyle the \cs{scriptscriptfont} is used. + +The primitive command +\cstoidx mathchoice\par +\begin{disp}\cs{mathchoice}\lb {\it D\/\rb\lb T\/\rb\lb S\/\rb\lb SS\/}\rb +\end{disp} +lets the user specify four variants of a formula for the +four styles. +\TeX\ constructs all four and inserts the appropriate one. + +%\point[math:class] Classes of mathematical objects +\section{Classes of mathematical objects} +\label{math:class} + +Objects in math mode belong to one of eight classes. Depending +\term math classes\par +on the class the object may be surrounded by +some amount of white space, +or treated specially in some way. Commands exist to force +symbols, or sequences of symbols, to act as +belonging to a certain class. +In the hexadecimal representation \verb>"xyzz> +the class is the \gr{3-bit number}~\n x. + +This is the list of classes and commands that force those +classes. The examples are from the plain format +(see the tables starting at page~\pageref{math:sym:tables}). +\begin{enumerate} \message{set a counter here!}%\SetCounter:item=-1 +\item {\em ordinary\/}: lowercase Greek characters and those symbols + that are `just symbols'; + the command \csidx{mathord} forces this class. +\item {\em large operator\/}: integral and sum signs, + and `big' objects such as \cs{bigcap} or \cs{bigotimes}; + the command \csidx{mathop} forces this class. + Characters that are + large operators are centred vertically, and they + may behave differently in display style from in the + other styles; see below. +\item {\em binary operation\/}: plus and minus, + and things such as \cs{cap} or \cs{otimes}; + the command \csidx{mathbin} forces this class. +\item {\em relation\/} (also called {\em binary relation\/}): + equals, less than, and greater than signs, subset and + superset, perpendicular, parallel; + the command \csidx{mathrel} forces this class. +\item {\em opening symbol\/}: opening brace, bracket, parenthesis, angle, + \altt + floor, ceiling; + the command \csidx{mathopen} forces this class. +\item {\em closing symbol\/}: closing brace, bracket, parenthesis, angle, + \altt + floor, ceiling; + the command \csidx{mathclose} forces this class. +\item {\em punctuation\/}: most punctuation marks, but + \n:~is a relation, the \cs{colon} is a punctuation colon; + the command \csidx{mathpunct} forces this class. +\item {\em variable family\/}: symbols in this class change font + with the \cs{fam} parameter; in plain \TeX\ uppercase + Greek letters and ordinary letters and digits are + in this class. +\end{enumerate} + +There is one further class: the {\em inner\/} subformulas. +No characters can be assigned to this class, but characters and +subformulas can be forced into it by \csidx{mathinner}. +The \gr{generalized fraction}s and \verb-\left...\right- groups +are inner formulas. Inner formulas are surrounded +by some white space; see the table below. + +Other subformulas than those that are inner are treated as +ordinary symbols. In particular, subformulas enclosed in +braces are ordinary: \verb-$a+b$- looks like `$a\mathop+b$', but +\message{Check a+b look}% +\verb-$a{+}b$- looks like~`$a{+}b$'. Note, however, that +in \verb-${a+b}$- the whole subformula is treated as an +ordinary symbol, not its components; +therefore the result is~`${a+b}$'. + +%\point Large operators and their limits +\section{Large operators and their limits} + +The large operators in the Computer Modern fonts come in +two sizes: one for text style and one for display style. +Control sequences such as \cs{sum} are simply defined by +\cs{mathchardef} to correspond to a position in a font: +\begin{verbatim} +\mathchardef\sum="1350 +\end{verbatim} +but if the +current style is display style, \TeX\ looks to see whether +that character has a successor in the font. + +Large operators in text style behave as if they are followed +\cstoidx limits\par\cstoidx nolimits\par +by \cs{nolimits}, which places the limits as sub/superscript +expressions after the +operator:\begin{disp}$\sum_{k=1}^\infty$\end{disp} +In display style they behave as if they are followed by +\cs{limits}, which places the limits over and under +the operator:\begin{disp}$\displaystyle\sum_{k=1}^\infty$\end{disp} +The successor mechanism (see page~\pageref{successor}) +\alt +lets \TeX\ take a larger variant +of the delimiter here. + +The integral sign has been defined in plain \TeX\ as +\begin{verbatim} +\mathchardef\intop="1352 \def\int{\intop\nolimits} +\end{verbatim} +which places the limits after the operator, even in display style: +\begin{disp}$\displaystyle\int_0^\infty e^{-x^2}\,dx=\sqrt{\pi}/2$ +\end{disp} + +With \verb-\limits\nolimits- or \verb-\nolimits\limits- the +last specification has precedence; the default placement +can be restored by \csidx{displaylimits}. For instance, +\begin{verbatim} +$ ... \sum\limits\displaylimits ... $ +\end{verbatim} +is equivalent to \begin{verbatim} +$ ... \sum ... $ +\end{verbatim} +and +\begin{verbatim} +$$ ... \sum\nolimits\displaylimits ... $$ +\end{verbatim} +is equivalent to +\begin{verbatim} +$$ ... \sum ... $$ +\end{verbatim} + +%\point Vertical centring: \cs{vcenter} +\section{Vertical centring: \protect\cs{vcenter}} + +Each formula has an {\em axis\/}, which is for an in-line +\term axis of math formulas\par\term centring of math formulas\par +formula about half the x-height of the surrounding +text; the exact value is the \cs{fontdimen22} of the +font in family~2, the symbol font, in the current style. + +The bar line in fractions is placed on the axis; large +operators, delimiters and \cs{vcenter} boxes are centred on it. + +A \csidx{vcenter}\label{vcenter} +box is a vertical box that is arranged +so that it is centred on the math axis. +It is possible to give a \n{spread} or \n{to} +specification with a \cs{vcenter} box. + +The \cs{vcenter} box is allowed only in math mode, and +it does not behave like other boxes; for instance, it can +not be stored in a box register. It does not qualify as +a~\gr{box}. See page~\pageref{tvcenter} for a macro that +repairs this. + +%\point[muglue] Mathematical spacing: \n{mu} glue +\section{Mathematical spacing: \n{mu} glue} +\label{muglue} + +Spacing around mathematical objects is measured in \n{mu} +\term math spacing\par\term math unit\par\term mu glue\par +units. A~\n{mu} is $1/18$th part of \cs{fontdimen6} +of the font in family~2 in the current style, +the `quad' value of the symbol font. + +%\spoint Classification of \n{mu} glue +\subsection{Classification of \n{mu} glue} + +The user can specify \n{mu} spacing by \cs{mkern} or~\cs{mskip}, +\cstoidx mkern\par\cstoidx mskip\par +but most \n{mu} glue is inserted automatically by \TeX, +based on the classes to which objects belong (see above). +First, here are some rules of thumb describing the global +behaviour. + +\begin{itemize} \item A \cs{thickmuskip} (default value in plain +\TeX: \n{5mu plus 5mu}) +\cstoidx thickmuskip\par +is inserted around (binary) relations, except where these are +preceded or followed by other relations or punctuation, and +except if they follow an open, or precede a close symbol. +\item A \csidx{medmuskip} (default value in plain +\TeX: \n{4mu plus 2mu minus 4mu}) +is put around binary operators. +\item A \csidx{thinmuskip} +(default value in plain \TeX: \n{3mu}) follows after +punctuation, and is put around inner objects, except where these +are followed by a close or preceded by an open symbol, and +except if the other object is a large operator or a +binary relation. +\item No \n{mu} glue is inserted after an open or before a close +symbol except where the latter is preceded by punctuation; +no \n{mu} glue is inserted also before punctuation, except where +the preceding object is punctuation or an inner object. +\end{itemize} + +The following table gives the complete definition of mu glue +between math objects. +\begin{disp}\leavevmode +\vbox{\offinterlineskip + \halign{#\enspace\hfil&#\enspace\hfil\vrule + &&\hfil\enspace#\hfil\strut\cr + \omit\hfil&\omit\hfil& 0:& 1:& 2:& 3:& 4:& 5:& 6:\cr + \omit\hfil&\omit\hfil&\hfill Ord&\hfill Op&\hfill Bin&\hfill Rel& + \hfill Open&\hfill Close&\hfill Punct&\hfill Inner\cr + \omit\hfil&\omit\hfil&\multispan8\hrulefill\cr + 0:&Ord& 0& 1&(2)&(3)& 0& 0& 0&(1)\cr + 1:&Op& 1& 1& *&(3)& 0& 0& 0&(1)\cr + 2:&Bin& (2)&(2)& *& *&(2)& *& *&(2)\cr + 3:&Rel& (3)&(3)& *& 0&(2)& *& *&(2)\cr + 4:&Open& 0& 0& *& 0& 0& 0& 0& 0\cr + 5:&Close& 0& 1&(2)&(3)& 0& 0& 0&(1)\cr + 6:&Punct&(1)&(1)& *&(1)&(1)&(1)&(1)&(1)\cr + &Inner&(1)& 1&(2)&(3)&(1)& 0&(1)&(1)\cr +% \omit\hfil&\omit\hfil&\multispan8\hrulefil\cr +}} +\end{disp} + +where the symbols have the following meanings: +\begin{itemize}\item 0, no space; 1, thin space; 2, medium space; + 3, thick space; +\item $(\cdot)$, insert only in text and display + mode, not in script or scriptscript mode; +\item cases * cannot occur, because a Bin object is converted + to Ord if it is the first in the list, preceded by + Bin, Op, Open, Punct, Rel, or followed by Close, + Punct, and Rel; also, a Rel is converted to Ord when + \alt + it is followed by Close or Punct. +\end{itemize} + +Stretchable \n{mu} glue is set according to the same rules that +govern ordinary glue. However, only \n{mu} glue on the outer +level can be stretched or shrunk; any \n{mu} glue enclosed +in a~group is set at natural width. + +%\spoint Muskip registers +\subsection{Muskip registers} + +Like ordinary glue, \n{mu} glue can be stored in registers, +\cstoidx muskip\par\cstoidx muskipdef\par\cstoidx newmuskip\par +the \cs{muskip} registers, +of which there are 256 in \TeX. +The registers are denoted by +\begin{disp}\cs{muskip}\gr{8-bit number}\end{disp} +and they can be assigned to a control sequence by +\begin{disp}\cs{muskipdef}\gr{control sequence}\gr{equals}\gr{8-bit number} +\end{disp} +and there is a macro that allocates unused registers: +\begin{disp}\cs{newmuskip}\gr{control sequence}\end{disp} +Arithmetic for mu glue exists as for glue; see +Chapter~\ref{glue}. + +%\spoint Other spaces in math mode +\subsection{Other spaces in math mode} + +In math mode space tokens are ignored; however, +the math code of the space character is \verb-"8000- +in plain \TeX, +so if its category is made `letter' or `other character', it +will behave like an active character in math mode. +See also page~\pageref{mcode:8000}. + +Admissible glue in math mode is of type~\gr{mathematical skip}, +which is either a \gr{horizontal skip} (see Chapter~\ref{hvmode}) +or~\cs{mskip}\gr{muglue}. Leaders in math mode can be specified +with a \gr{mathematical skip}. + +A glue item preceded by \csidx{nonscript} +is cancelled if it occurs in scriptstyle or scriptscriptstyle. + +Control space functions in math mode +\alt +as it does in horizontal mode. + +In-line formulas are surrounded by kerns of size +\csidx{mathsurround}, the so-called `math-on' and +`math-off' items. Line breaking can occur at the front of +the math-off kern if it is followed by glue. + +%\point Generalized fractions +\section{Generalized fractions} + +Fraction-like objects can be set with six primitive commands +of type \gr{generalized fraction}. +\term generalized fractions\par +Each of these takes the preceding and the following subformulas +and puts them over one another, if necessary with a fraction +bar and with delimiters. +\begin{description} \item [\csidx{over}] + is the ordinary fraction; the bar thickness is \cs{fontdimen8} + of the extension font: + \begin{disp}\verb>$\pi\over2$>\quad gives\quad `$\pi\over2$'\message{pi over 2}\end{disp} +\item [\csidx{atop}] + is equivalent to a fraction with zero bar thickness: + \begin{disp}\verb>$\pi\atop2$>\quad gives\quad `$\pi\atop2$'\end{disp} +\item [\csidx{above}\gr{dimen}] + specifies the thickness + of the bar line explicitly: + \begin{disp}\verb>$\pi\above 1pt 2$>\quad gives\quad `$\pi\above 1pt 2$'\end{disp} +\end{description} + +To each of these three there corresponds a \cs{...withdelims} variant +\cstoidx overwithdelims\par\cstoidx atopwithdelims\par +\cstoidx abovewithdelims\par +that lets the user specify delimiters for the expression. +For example, the most general command, in terms of which +all five others could have been defined, is +\begin{disp}\cs{abovewithdelims}\gr{delim$_1$}\gr{delim$_2$}\gr{dimen}. +\end{disp} +Delimiters in these generalized fractions do not grow with the +enclosed expression: in display mode a delimiter is taken +which is at least \cs{fontdimen20} high, otherwise +\alt +it has to be +at least \cs{fontdimen21} high. +These dimensions are taken +from the font in family~2, the symbol font, in the current style. + +The control sequences \cs{over}, \cs{atop}, and \cs{above} +are primitives, although they could have been defined +as \cs{...withdelims..}, that is, with two null delimiters. +Because of these implied surrounding null delimiters, +there is a kern of size \cs{nulldelimiterspace} before and after +these simple generalized fractions. + +%\point Underlining, overlining +\section{Underlining, overlining} + +The primitive commands \csidx{underline} and \csidx{overline} take a +\gr{math field} argument, that is, a \gr{math symbol} or +a group, and draw a line under or over it. +The result is an `Under' or `Over' atom, which +is appended to the current math list. +The line thickness is font dimension~8 of the extension font, +which also determines the clearance between the line and +the \gr{math field}. + +Various other \cs{over...} and \cs{under...} commands exist +in plain \TeX; +these are all macros +that use the \TeX\ \cs{halign} command. + +%\point Line breaking in math formulas +\section{Line breaking in math formulas} + +In-line formulas can be broken after relations and binary operators. +\cstoidx relpenalty\par\cstoidx binoppenaly\par +\term penalties in math mode\par +The respective penalties are the \cs{relpenalty} +and the~\cs{binoppenalty}. However, \TeX\ will only break +after such symbols if they are not enclosed in braces. +Other breakpoints can be created with~\cs{allowbreak}, +\cstoidx allowbreak\par\term breakpoints in math lists\par +which is an abbreviation for~\cs{penalty0}. + +Unlike in horizontal or vertical mode where putting two penalties +in a row is equivalent to just placing the smallest one, +in math mode a penalty placed at a break point \ldash that is, +after a relation or binary operator \rdash will effectively +replace the old penalty by the new one. + +%\point[fam23:fontdims] Font dimensions of families 2 and 3 +\section{Font dimensions of families 2 and 3} +\label{fam23:fontdims} + +If a font is used in text mode, \TeX\ will look at its +first 7 \cs{fontdimen} parameters +(see page~\pageref{font:dims}), for instance to +control spacing. +In math, however, more font dimensions are needed. +\TeX\ will look at the first 22 parameters of the +fonts in family~2, and the first 13 of the fonts in +family~3, to control various +aspects of math typesetting. The next two subsections +have been quoted loosely from~\cite{BB:ISO}. + +%\spoint Symbol font attributes +\subsection{Symbol font attributes} + +Attributes of the font in family 2 mainly specify the +\term symbol font\par +initial vertical positioning +of parts of fractions, subscripts, superscripts, et cetera. +The position determined by applying these +attributes may be further modified because of other +conditions, for example the presence of a fraction bar. + +One text font dimension, number~6, +the quad, determines the size of mu glue; +see above. + +Fraction numerator attributes: minimum shift up, from +the main baseline, of the baseline of the numerator +of a generalized fraction, +\begin{enumerate} \message{set a counter here!}%\SetCounter:item=7 +\item num1: + for display style, +\item num2: + for text style or smaller if a fraction bar is present, +\item num3: + for text style or smaller if no fraction bar is present. +\end{enumerate} + +Fraction denominator attributes: minimum shift down, from +the main baseline, of the baseline of the denominator +of a generalized fraction, +\begin{enumerate} \message{set a counter here!}%\SetCounter:item=10 +\item denom1: +for display style, +\item denom2: +for text style or smaller. +\end{enumerate} + +Superscript attributes: minimum shift up, from the main baseline, +of the baseline of a superscript, +\begin{enumerate} \message{set a counter here!}%\SetCounter:item=12 +\item sup1: +for display style, +\item sup2: +for text style or smaller, non-cramped, +\item sup3: +for text style or smaller, cramped. +\end{enumerate} + +Subscript attributes: minimum shift down, from the main baseline, +of the baseline of a subscript, +\begin{enumerate} \message{set a counter here!}%\SetCounter:item=15 +\item sub1: +when no superscript is present, +\item sub2: +when a superscript is present. +\end{enumerate} + +Script adjustment attributes: for use only with non-glyph, +that is, composite, objects. +\begin{enumerate} \message{set a counter here!}%\SetCounter:item=17 +\item sup\_drop: +maximum distance of superscript baseline below top of nucleus +\item sub\_drop: +minimum distance of subscript baseline below bottom of nucleus. +\end{enumerate} + +Delimiter span attributes: height plus depth of delimiter enclosing +a generalized fraction, +\begin{enumerate} \message{set a counter here!}%\SetCounter:item=19 +\item delim1: +in display style, +\item delim2: +in text style or smaller. +\end{enumerate} + +A parameter with many uses, the height of the math axis, +\begin{enumerate} \message{set a counter here!}%\SetCounter:item=21 +\item axis\_height: +the height above the baseline +of the fraction bar, and the centre of large delimiters +and most operators and relations. This position is +used in vertical centring operations. +\end{enumerate} + +%\spoint Extension font attributes +\subsection{Extension font attributes} + +Attributes of the font in family 3 mostly specify +the way the limits of large operators are set. + +The first parameter, number 8, default\_rule\_thickness, +serves many purposes. It +is the thickness of the rule used for overlines, +underlines, radical extenders (square root), +and fraction bars. Various clearances are also specified +in terms of this dimension: between the fraction bar and +the numerator and denominator, between an object and +the rule drawn by an underline, overline, or radical, +and between the bottom of superscripts and top of subscripts. + +Minimum clearances around large operators are as follows: +\begin{enumerate} \message{set a counter here!}%\SetCounter:item=8 +\item big\_op\_spacing1: +minimum clearance between baseline of upper limit and top +of large operator; see below. +\item big\_op\_spacing2: +minimum clearance between bottom of large operator and top of +lower limit. +\item big\_op\_spacing3: +minimum clearance between baseline of +upper limit and top of large operator, +taking into account depth of upper limit; see below. +\item big\_op\_spacing4: +minimum clearance between bottom of large operator and top of lower +limit, taking into account height of lower limit; see below. +\item big\_op\_spacing5: +clearance above upper limit or below lower limit of a large operator. +\end{enumerate} +The resulting clearance above an operator is the maximum +of parameter~7, and parameter~11 minus the depth of the +upper limit. +The resulting clearance below an operator is the maximum +of parameter~10, and parameter~12 minus the height of the +lower limit. + +%\spoint Example: subscript lowering +\subsection{Example: subscript lowering} + +The location of a subscript depends on whether there +\alt +\howto Adjust subscript lowering\par +is a superscript; for instance +\begin{disp} $X_1+Y^2_1=1$\end{disp} +If you would rather have that look like +\begin{disp} $\global\tempdima=\fontdimen16\textfont2\relax + \global\tempdimb=\fontdimen17\textfont2\relax + \fontdimen16\textfont2=3pt \fontdimen17\textfont2=3pt + X_1+Y^2_1=1$,$\fontdimen16\textfont2=\tempdima\relax + \fontdimen17\textfont2=\tempdimb\relax$ +\end{disp} +\message{check lowering} +it suffices to specify +\begin{verbatim} +\fontdimen16\textfont2=3pt \fontdimen17\textfont2=3pt +\end{verbatim} +which makes the subscript drop equal in both cases. + +%\subject[displaymath] Display Math +\endofchapter +\chapter{Display Math}\label{displaymath} + +Displayed formulas are set on a line of their own, usually +somewhere in a paragraph. This chapter explains +how surrounding white space (both above/below and to the +left/right) is calculated. + + +\begin{inventory} +\item [\cs{abovedisplayskip \cs{belowdisplayskip}}] +\mdqon + Glue above/""below a display. +\mdqoff + Plain \TeX\ default:~\n{12pt plus 3pt minus 9pt} + +\item [\cs{abovedisplayshortskip \cs{belowdisplayshortskip}}] +\mdqon + Glue above/""below a display if the line preceding the display +\mdqoff + was short. + Plain \TeX\ defaults:~\n{0pt plus 3pt} and + \n{7pt plus 3pt minus 4pt} respectively. + +\item [\cs{predisplaypenalty \cs{postdisplaypenalty}}] +\mdqon + Penalty placed in the vertical list above/""below a display. +\mdqoff + Plain \TeX\ defaults:~\n{10$\,$000} and~\n{0} + respectively. + +\item [\cs{displayindent}] + Distance by which the box, in which the display + is centred, is indented owing to hanging indentation. + +\item [\cs{displaywidth}] + Width of the box in which the display is centred. + +\item [\cs{predisplaysize}] + Effective width of the line preceding the display. + +\item [\cs{everydisplay}] + Token list inserted at the start of a display. + +\item [\cs{eqno}] + Place a right equation number in a display formula. + +\item [\cs{leqno}] + Place a left equation number in a display formula. + +\end{inventory} + +%\point Displays +\section{Displays} + +\TeX\ starts building a display when it encounters two +\term displays\par +math shift characters (characters of category~3, +\verb>$>~in plain \TeX) in a row. +Another such pair (possibly followed +\alt by one optional space) indicates the end of the display. + +Math shift is a \gr{horizontal command}, but displays are only +allowed in unrestricted horizontal mode +(\verb>$$>~is an empty math formula in restricted horizontal mode). +Displays themselves, however, are started in the +surrounding (possibly internal) vertical mode in order to calculate +quantities such as~\cs{prevgraf}; the result of the display is +appended to the vertical list. + +The part of the paragraph above the display is broken into +lines as an independent paragraph (but \cs{prevgraf} is +carried over; see below), and the remainder of the +paragraph is set, starting with an empty list and \cs{spacefactor} +equal to~1000. +The \cs{everypar} tokens are not inserted for the part of the +paragraph after the display, nor is \cs{parskip} glue inserted. + +Right at the beginning of the display the \csidx{everydisplay} +token list is inserted (but after the calculation of +\cs{displayindent}, \cs{displaywidth}, and \cs{predisplaysize}). +See page~\pageref{left:display} for an example of the use +of \cs{everydisplay}. + +The page builder is exercised +before the display +(but after the \cs{everydisplay} tokens have been inserted), +and after the display finishes. + +The `display style' of math typesetting was treated in +Chapter~\ref{mathfont}. + +%\point Displays in paragraphs +\section{Displays in paragraphs} + +Positioning of a display in a paragraph may be influenced +by hanging indentation or a \cs{parshape} specification. +For this, \TeX\ uses the \cs{prevgraf} parameter +(see Chapter~\ref{par:shape}), and +acts as if the display is three lines deep. + +If $n$ is the value of \cs{prevgraf} when the display starts +\ldash so there are $n$ lines of text above the display \rdash +\cs{prevgraf} is set to to $n+3$ when the paragraph resumes. +The display occupies, as it were, lines $n+1$, $n+2$, and~$n+3$. +The shift and line width for the display are those +that would hold for line~$n+2$. + +The shift for the display is recorded in \cs{displayindent}; +\cstoidx displayindent\par\cstoidx displaywidth\par +the line width is recorded in \cs{displaywidth}. These parameters +(and the \cs{predisplaysize} explained below) +are set immediately after the \verb>$$> has been scanned. +Usually they are equal to zero and \cs{hsize} respectively. +The user can change the values of these parameters; +\TeX\ will use the +values that hold after the math list +of the display has been processed. + +Note that a display is vertical material, and therefore +not influenced by settings of \cs{leftskip} and \cs{rightskip}. + +%\point Vertical material around displays +\section{Vertical material around displays} + +A display is preceded in the vertical list by +\begin{itemize}\item a penalty of size \cs{predisplaypenalty} + \cstoidx predisplaypenalty\par\cstoidx abovedisplayskip\par + \cstoidx abovedisplayshortskip\par +(plain \TeX\ default~$10\,000$), and +\item glue of size \cs{abovedisplayskip} +or \cs{abovedisplayshortskip}; this glue is omitted in +cases where a~\cs{leqno} equation number is set on +a line of its own (see below).\end{itemize} +A display is followed by +\begin{itemize}\item a penalty of size \cs{postdisplaypenalty} + \cstoidx postdisplaypenalty\par\cstoidx belowdisplayskip\par + \cstoidx belowdisplayshortskip\par +(default~0), and possibly +\item glue of size \cs{belowdisplayskip} or +\cs{belowdisplayshortskip}; this glue is omitted in cases +where an~\cs{eqno} equation number is set on a line of +its own (see below).\end{itemize} + +The `short' variants of the glue are taken if +there is no \cs{leqno} left equation number, and if +the last line of the paragraph above the display is +short enough for the display to be raised a bit without +coming too close to that line. +In order to decide this, the effective width of the +preceding line is saved in \csidx{predisplaysize}. +This value is calculated immediately after the opening \verb>$$> +of the display has +been scanned, together with the \cs{displaywidth} +and \cs{displayindent} explained above. + +Remembering that the part of the paragraph above the display +has already been broken into lines, the following method +for finding the effective width of the last line ensues. +\TeX\ takes the last box of the list, which is a horizontal +box containing the last line, and locates the right edge +of the last box in it. The \cs{predisplaysize} is then +the place of that rightmost edge, plus any amount by which +the last line was shifted, plus two ems in the current font. + +There are two exceptions to this. The \cs{predisplaysize} +is taken to be $-$\cs{maxdimen} if there was no previous line, +that is, +the display started the paragraph, or it followed another display; +\cs{predisplaysize} is taken to be \cs{maxdimen} +\term machine dependence\par +if the glue in the last line was not set at its natural width, +which may happen if the \cs{parfillskip} contained only finite +stretch. The reason for the last clause is that glue +\mdqon +setting is slightly machine"-dependent, and such dependences +\mdqoff +should be kept out of \TeX's global decision processes. + +%\point Glue setting of the display math list +\section{Glue setting of the display math list} + +The display has to fit in \cs{displaywidth}, +but in addition to the formula there +may be an equation number. The minimum separation +between the formula and the equation number should +be one em in the symbol font, that is, +\mdqon +\cs{font\-dimen\-6}""\cs{textfont2}. +\mdqoff + +If the formula plus any equation number +and separation fit into \cs{displaywidth}, +the glue in the formula is set at its natural width. +If it does not fit, +but the formula contains enough shrink, it is shrunk. +Otherwise \TeX\ puts any equation number +on a line of its own, and the glue in the formula is +set to fit it in \cs{displaywidth}. +With the equation +number on a separate line the formula may now very well fit in the +display width; however, +if it was a very long formula the box in which it is +set may still be overfull. \TeX\ nevers breaks a displayed +formula. + +%\point Centring the display formula: displacement +\section{Centring the display formula: displacement} + +Based on the width of the box containing the formula \ldash which +may not really `contain' it; it may be overfull \rdash +\TeX\ tries to centre the formula in the \cs{displaywidth}, +that is, without taking the equation number into account. +Initially, a displacement is calculated that is +half the difference between \cs{displaywidth} and the +width of the formula box. + +However, if there is an equation number that will not +be put on a separate line and the displacement is less than +twice the width of the equation number, a new displacement +is calculated. This new displacement is zero if the formula +started with glue; otherwise it is such that the +formula box is centred in the space left by the equation +number. + +If there was no equation number, or if the equation number +will be put on a separate line, the formula box +is now placed, shifted right by \cs{displayindent} plus +the displacement calculated above. + +%\point Equation numbers +\section{Equation numbers} + +The user can specify a equation number for a display +by ending it with +\cstoidx eqno\par\cstoidx leqno\par\term equation numbering\par +\begin{Disp}\cs{eqno}\gr{math mode material}\verb>$$>\end{Disp} +for an equation number placed on the right, or +\begin{Disp}\cs{leqno}\gr{math mode material}\verb>$$>\end{Disp} +for an equation number placed on the left. + +%\spoint Ordinary equation numbers +\subsection{Ordinary equation numbers} + +Above it was described how \TeX\ calculates a displacement +from the display formula and the equation number, if this +is to be put on the same line as the formula. + +If the equation number was a \cs{leqno} number, +\TeX\ places a box containing +\begin{itemize}\item the equation number, +\item a kern with the size of the displacement calculated, and +\item the formula.\end{itemize} +This box is shifted right by \cs{displayindent}. + +If the equation number was an \cs{eqno} number, +\TeX\ places a box containing +\begin{itemize}\item the formula, +\item a kern with the size of the displacement calculated, and +\item the equation number.\end{itemize} +This box is shifted right by \cs{displayindent} plus +the displacement calculated. + +%\spoint The equation number on a separate line +\subsection{The equation number on a separate line} + +Since displayed formulas may become rather big, \TeX\ can decide +(as was described above) +that any equation number should be placed on a line of its own. +A~left-placed equation number is then to be placed above the +display, in a box that is shifted right by \cs{displayindent}; +a right-placed equation number will be placed below the display, +in a box that is shifted to the right +by \cs{displayindent} plus \cs{displaywidth} minus the width of +the equation number box. + +In both cases a penalty of $10\,000$ is placed between the equation +number box and the formula. + +\TeX\ does not put extra glue above a left-placed +equation number or below +a right-placed equation number; \TeX\ here relies on +the baselineskip mechanism. + + +%\point[left:display] Non-centred displays +\section{Non-centred displays} +\label{left:display} + +As a default, \TeX\ will centre displays. +\term displays, non-centred\par +In order to get non-centred displays some +macro trickery is needed. + +One approach would +be to write a macro \cs{DisplayEquation} +that would basically look like +\begin{verbatim} +\def\DisplayEquation#1{% + \par \vskip\abovedisplayskip + \hbox{\kern\parindent$\displaystyle#1$} + \vskip\belowdisplayskip \noindent} +\end{verbatim} +but it would be nicer if one could just write +\begin{verbatim} +$$ ... \eqno ... $$ +\end{verbatim} +\mdqon +and having this come out as a left"-aligning display. +\mdqoff + +Using the \cs{everydisplay} token list, the above +idea can be realized. The basic idea is to write +\begin{verbatim} +\everydisplay{\IndentedDisplay} +\def\IndentedDisplay#1$${ ... +\end{verbatim} +so that the macro \cs{IndentedDisplay} +will receive the formula, including any equation number. +The first step is now to extract an equation number +if it is present. This makes creative use of delimited +macro parameters.\begin{verbatim} +\def\ExtractEqNo#1\eqno#2\eqno#3\relax + {\def\Equation{#1}\def\EqNo{#2}} +\def\IndentedDisplay#1$${% + \ExtractEqNo#1\eqno\eqno\relax +\end{verbatim} +Next the equation should be set in the available +space \cs{displaywidth}: +\begin{verbatim} + \hbox to \displaywidth + {\kern\parindent + $\displaystyle\Equation$\hfil$\EqNo$}$$ + } +\end{verbatim} +Note that the macro ends in the closing \verb>$$> +to balance the opening dollars that caused +insertion of the \cs{everydisplay} tokens. +This also means that the box containing the +displayed material will automatically be +surrounded by \cs{abovedisplayskip} and +\cs{belowdisplayskip} glue. +There is no need to use \cs{displayindent} anywhere +in this macro, because \TeX\ itself will shift the +display appropriately. + +% \begin{comment} +% \endinput +% baselineskip around displays? + + + +% \end{comment} +%%%% end of input file [math] + +%\InputFile:align +%%%% this is input file [align] +%\subject[align] Alignment +\endofchapter +\chapter{Alignment}\label{align} + +\TeX\ provides a general alignment mechanism for making tables. +\term alignments\par\term tables\par + +\begin{inventory} +\item [\cs{halign}] + Horizontal alignment. + +\item [\cs{valign}] + Vertical alignment. + +\item [\cs{omit}] + Omit the template for one alignment entry. + +\item [\cs{span}] + Join two adjacent alignment entries. + +\item [\cs{multispan}] + Macro to join a number of adjacent alignment entries. + +\item [\cs{tabskip}] + Amount of glue in between columns (rows) + of an \cs{halign} (\cs{valign}). + +\item [\cs{noalign}] + Specify vertical (horizontal) + material to be placed in between rows (columns) of + an \cs{halign} (\cs{valign}). + +\item [\cs{cr}] + Terminate an alignment line. + +\item [\cs{crcr}] + Terminate an alignment line if it has + not already been terminated by~\cs{cr}. + +\item [\cs{everycr}] + Token list inserted after every \cs{cr} or non-redundant + \cs{crcr}. + +\item [\cs{centering}] + Glue register in plain \TeX\ for centring + \cs{eqalign} and \cs{eqalignno}. + Value: \n{0pt plus 1000pt minus 1000pt} + +\item [\cs{hideskip}] + Glue register in plain \TeX\ to make alignment entries invisible. + Value: \n{-1000pt plus 1fill} + +\item [\cs{hidewidth}] + Macro to make preceding or following entry invisible. + +\end{inventory} + +%\point Introduction +\section{Introduction} + +\TeX\ has a sophisticated alignment mechanism, based on +templates, with one template entry per column or row. +The templates may contain any common elements +of the table entries, and in general they contain +instructions for typesetting the entries. +\TeX\ first calculates widths (for \cs{halign}) or heights +(for \cs{valign}) of all entries; +then it typesets the whole alignment using in each column (row) +the maximum width (height) of entries in that column (row). + +%\point Horizontal and vertical alignment +\section{Horizontal and vertical alignment} + +The two alignment commands in \TeX\ are +\cstoidx halign\par\cstoidx valign\par +\begin{disp}\cs{halign}\gr{box specification}\lb\gr{alignment material}\rb +\end{disp} for horizontal alignment of columns, and +\begin{disp}\cs{valign}\gr{box specification}\lb\gr{alignment material}\rb +\end{disp} for vertical alignment of rows. +\cs{halign} is a \gr{vertical command}, and +\cs{valign} is a \gr{horizontal command}. + +The braces induce a new level of grouping; they can be +implicit. + +The discussion below will mostly focus on horizontal +alignments, but, replacing `column' by `row' and vice versa, +it applies to vertical alignments too. + +%\spoint Horizontal alignments: \cs{halign} +\subsection{Horizontal alignments: \cs{halign}} + +Horizontal alignments yield a list of horizontal boxes, the rows, +\term horizontal alignment\par +which are placed on the surrounding vertical list. +The page builder is exercised after the alignment rows have been +added to the vertical list. +The value of \cs{prevdepth} that holds before the alignment +is used for the baselineskip of the first row, +and after the alignment \cs{prevdepth} is set to a value based +on the last row. + +Each entry is processed in a group of its own, +in restricted horizontal mode. + +A special type of horizontal alignment exists: the +\term display alignment\par +display alignments, specified as +\begin{disp}\n{\$\$}\gr{assignments}\cs{halign}\gr{box specification}\lb\n{...}\rb + \gr{assignments}\n{\$\$}\end{disp} +Such an alignment is shifted by \cs{displayindent} (see +Chapter~\ref{displaymath}) and surrounded by +\cs{abovedisplayskip} and \cs{belowdisplayskip} glue. + +%\spoint Vertical alignments: \cs{valign} +\subsection{Vertical alignments: \cs{valign}} + +Vertical alignments are `rotated' horizontal alignments: +\term vertical alignment\par +they are placed on the surrounding horizontal lists, +and yield a row of columns. The \cs{spacefactor} value +is treated the same way as the \cs{prevdepth} for horizontal +alignments: the value current before the alignment is used +for the first column, and the value reached after the last column +is used after the alignment. In between columns the \cs{spacefactor} +value is~1000. + +Each entry is in a group of its own, and it is processed +in internal vertical mode. + +%\spoint Material between the lines: \cs{noalign} +\subsection{Material between the lines: \cs{noalign}} + +Material that has to be contained in the alignment, but +should not be treated as an entry or series of entries, +\cstoidx noalign\par +can be given by +\begin{disp}\cs{noalign}\gr{filler}\lb\gr{vertical mode material}\rb +\end{disp} for horizontal alignments, and +\begin{disp}\cs{noalign}\gr{filler}\lb\gr{horizontal mode material}\rb +\end{disp} for vertical alignments. + +Examples are +\begin{verbatim} +\noalign{\hrule} +\end{verbatim} +for drawing a horizontal rule +between two lines of an \cs{halign}, +and \begin{verbatim} +\noalign{\penalty100} +\end{verbatim} +for discouraging a page break (or line break) in +between two rows (columns) of an \cs{halign} (\cs{valign}). + +%\spoint Size of the alignment +\subsection{Size of the alignment} + +The \gr{box specification} can be used to give the alignment +a predetermined size: for instance +\begin{verbatim} +\halign to \hsize{ ... } +\end{verbatim} +Glue contained in the entries of the alignment has no role in this; +any stretch or +shrink required is taken from the \cs{tabskip} glue. +This is explained below. + +%\point The preamble +\section{The preamble} + +Each line in an alignment is terminated by \cs{cr}; +the first line is called the {\it template line}. +It is of the form +\begin{disp}\n{$u_1$\#$v_1$\&...\&$u_n$\#$v_n$}\cs{cr}\end{disp} +where each $u_i$, $v_i$ is a (possibly empty) arbitrary sequence +of tokens, and the template entries are separated by +the {\italic alignment tab +\term alignment tab\par +character} (\n\&~in plain \TeX), +that is, any character of category~4. + +A $u_i$\n\#$v_i$ sequence is the template that will be +used for the $i\,$th column: whatever sequence $\alpha_i$ +the user specifies +as the entry for that column will be inserted at the +parameter character. The sequence $u_i\alpha_iv_i$ is +then processed to obtain the actual entry for the $i\,$th +column on the current line. See below for more details. + +The length $n$ of the template line need +not be equal to the actual number of columns in the alignment: +the template is used only for as many items as are specified +on a line. Consider as an example +\begin{verbatim} +\halign{a#&b#&c#\cr 1&2\cr 1\cr} +\end{verbatim} +which has a three-item template, but the rows have only +one or two items. The output of this is +\begin{disp}\leavevmode\vbox{\halign{a#&b#&c#\cr 1&2\cr 1\cr}}\end{disp} + +%\spoint Infinite preambles +\subsection{Infinite preambles} + +For the case where the number of columns is not known in advance, +for instance if the alignment is to be used in a macro where +the user will specify the columns, it is possible to +specify that a trailing piece of the +preamble can be repeated arbitrarily many times. +By preceding it with \n\&, an entry can be marked as the +start of this repeatable part of the preamble. +See the example of \cs{matrix} below. + +When the whole preamble is to be repeated, there will be +an alignment tab character at the start of the first entry: +\begin{verbatim} +\halign{& ... & ... \cr ... } +\end{verbatim} +If a starting portion of the preamble is to be exempted from +repetition, a double alignment tab will occur: +\begin{verbatim} +\halign{ ... & ... & ... && ... & ... \cr ... } +\end{verbatim} + +The repeatable part need not be used an integral +number of times. The alignment rows can end at any time; +the rest of the preamble is then not used. + +%\spoint Brace counting in preambles +\subsection{Brace counting in preambles} + +Alignments may appear inside alignments, so \TeX\ uses the +following rule to determine to which alignment +an \n\& or \cs{cr} control sequence belongs: +\begin{disp} All tab characters and \cs{cr} tokens of an alignment + should be on the same level of grouping.\end{disp} +From this it follows that tab characters and \cs{cr} tokens +can appear inside an entry if they are nested in braces. +This makes it possible to have nested alignments. + +%\spoint Expansion in the preamble +\subsection{Expansion in the preamble} + +All tokens in the preamble \ldash apart from the tab characters \rdash +are stored for insertion in the entries of the alignment, +but a token preceded by \csidx{span} is expanded while +the preamble is scanned. See below for the function of +\cs{span} in the rest of the alignment. + +%\spoint \cs{tabskip} +\subsection{\cs{tabskip}} + +Entries in an alignment are set to take the width of the +largest element in their column. +Glue for separating columns can be specified by assigning +to \csidx{tabskip}. +\altt +\TeX\ inserts this glue in +between each pair of columns, and before the first and after the +last column. + +The value of \cs{tabskip} that holds outside the alignment is +used before the first column, and after all subsequent columns, +unless the preamble contains assignments to \cs{tabskip}. +Any assignment to \cs{tabskip} is executed while \TeX\ is scanning +the preamble; the value that holds when a tab character is +reached will be used at that place in each row, and after all subsequent +columns, unless further assignments occur. +The value of \cs{tabskip} that holds when \cs{cr} is reached +is used after the last column. + +Assignments to \cs{tabskip} in the preamble are local to the +alignment, but not to the entry where they are given. +These assignments are ordinary glue assignments: +they remove any optional trailing space. + +As an example, in the following table there is no tabskip +glue before the first and after the last column; +in between all columns there is stretchable tabskip. +\begin{verbatim} +\tabskip=0pt \halign to \hsize{ + \vrule#\tabskip=0pt plus 1fil\strut& + \hfil#\hfil& \vrule#& \hfil#\hfil& \vrule#& \hfil#\hfil& + \tabskip=0pt\vrule#\cr + \noalign{\hrule} + &\multispan5\hfil Just a table\hfil&\cr + \noalign{\hrule} + &one&&two&&three&\cr &a&&b&&c&\cr + \noalign{\hrule} + } +\end{verbatim} +The result of this is +\begin{disp}\PopListLevel +\leavevmode\message{single indent and sufficient vertical}% +\hbox{\leftskip0pt \rightskip0pt + \vbox{\offinterlineskip +\tabskip=0pt \halign to \hsize{\strut + \vrule#\tabskip=0pt plus 1fil\strut& + \hfil#\hfil& \vrule#& \hfil#\hfil& + \vrule#& \hfil#\hfil& + \tabskip=0pt\vrule#\cr + \noalign{\hrule} + &\multispan5\hfil Just a table\hfil&\cr + \noalign{\hrule} + &one&&two&&three&\cr + &a&&b&&c&\cr + \noalign{\hrule} + }}}\end{disp} +All of the vertical rules +of the table are in a separate column. This is the only way +to get the space around the items to stretch. + +%\point The alignment +\section{The alignment} + +After the template line any number of lines terminated by \cs{cr} +can follow. \TeX\ reads all of these lines, processing the +entries in order to find the maximal width (height) in +each column (row). +Because all entries are kept in memory, +long tables can overflow \TeX's main memory. +For such tables it is better to write a special-purpose macro. + +%\spoint Reading an entry +\subsection{Reading an entry} + +Entries in an alignment are composed of the +constant $u$ and $v$ parts +of the template, and the variable $\alpha$ part. +Basically \TeX\ forms the sequence of tokens $u\alpha v$ +and processes this. However, there are two special cases +where \TeX\ has to expand before it forms this sequence. + +Above, the \cs{noalign} command was described. +Since this requires a different treatment from other +alignment entries, +\TeX\ expands, after it has read a \cs{cr}, +the first token of the first $\alpha$ string +of the next line to +see whether that is or expands to \cs{noalign}. +Similarly, for all entries +in a line the first token is expanded to see +whether it is or expands to \cs{omit}. This control sequence +will be described below. + +Entries starting with an \cs{if...} conditional, or a macro +expanding to one, may be misinterpreted owing to this +premature expansion. For example, +\begin{verbatim} +\halign{$#$\cr \ifmmode a\else b\fi\cr} +\end{verbatim} +will give +\begin{disp}\leavevmode + \vbox{\halign{$#$\cr \ifmmode a\else b\fi\cr}}\end{disp} +because the conditional is evaluated before math mode has been set up. +The solution is, as in many other cases, to insert a +\cs{relax} control sequence to stop the expansion. +Here the \cs{relax} has to be inserted at the start of the +alignment entry. + +If neither \cs{noalign} nor \cs{omit} (see below) is found, +\TeX\ will process an input stream composed +of the $u$ part, the $\alpha$ tokens +(which are delimited by either \n\& or \cs{span}, see below), +and the $v$ part. + +Entries are delimited by \n\&, \cs{span}, or \cs{cr}, but +only if such a token occurs on the same level of grouping. +This makes it possible to have an alignment as an entry of +another alignment. + +%\spoint Alternate specifications: \cs{omit} +\subsection{Alternate specifications: \cs{omit}} + +The template line will rarely be sufficient to describe +all lines of the alignment. For lines where items should be +set differently the command \csidx{omit} exists: +if the first token in an entry is (or expands to) \cs{omit} +the trivial template \n\# is used instead of +what the template line specifies. + +\begin{example} The following alignment uses the same template for +all columns, but in the second column an \cs{omit} command +is given. +\begin{verbatim} +\tabskip=1em +\halign{&$<#>$\cr a&\omit (b)&c \cr} +\end{verbatim} +The output of this is +\begin{disp}\leavevmode\vbox{\tabskip=1em +\halign{&$<#>$\cr a&\omit (b)&c \cr}} +\end{disp} +\end{example} + +%\spoint Spanning across multiple columns: \cs{span} +\subsection{Spanning across multiple columns: \cs{span}} + +Sometimes it is desirable to have material spanning several +columns. The most obvious example is that of a heading above +a table. For this \TeX\ provides the \cs{span} command. + +Entries are delimited either by \n\&, by \cs{cr}, or by \csidx{span}. +In the last case \TeX\ will omit the tabskip glue that +would normally follow the entry thus delimited, and +it will typeset the material just read plus the following +entry in the joint space available. + +As an example, +\begin{verbatim} +\tabskip=1em +\halign{&#\cr a&b&c&d\cr a&\hrulefill\span\hrulefill&d\cr} +\end{verbatim} +gives +\begin{disp}\leavevmode\vbox{\tabskip=1em +\halign{&#\cr a&b&c&d\cr a&\hrulefill\span\hrulefill&d\cr}} +\end{disp} Note that there is no tabskip glue in between the +two spanned columns, but there is tabskip glue before the +\alt +first column and after the last. + +Using the \cs{omit} command this same alignment could +have been generated as +\begin{verbatim} +\halign{&#\cr a&b&c&d\cr a&\hrulefill\span\omit&d\cr} +\end{verbatim} + +The \cs{span}\cs{omit} combination is used in the +plain \TeX\ macro +\cs{multispan}: for instance +\begin{disp}\cs{multispan4}\quad gives\quad \verb>\omit\span\omit\span\omit\span\omit> +\end{disp} which spans across three tabs, and removes the templates +of four entries. +Repeating the above example once again: +\begin{verbatim} +\halign{&#\cr a&b&c&d\cr a&\multispan2\hrulefill&d\cr} +\end{verbatim} +The argument of \cs{multispan} is a single token, +not a number, +so in order to span more than 9 columns the argument +should be enclosed in braces, for instance \verb>\multispan{12}>. +\alt +Furthermore, a space after a single-digit argument +will wind up in the output. + +For a `low budget' solution to spanning columns plain \TeX\ has the +macro \csidx{hidewidth}, defined by +\begin{verbatim} +\newskip\hideskip \hideskip=-1000pt plus 1fill +\def\hidewidth{\hskip\hideskip} +\end{verbatim} +Putting \cs{hidewidth} at the beginning or end of an alignment entry +will make its width zero, with the material in the entry +sticking out to the left or right respectively. + + +%\spoint Rules in alignments +\subsection{Rules in alignments} + +Horizontal rules inside a horizontal alignment will mostly +\term rules in alignments\par +\howto Draw rules in an alignment\par +be across the width of the alignment. The easiest way +to attain this is to use \begin{verbatim} +\noalign{\hrule} +\end{verbatim} +lines inside the alignment. If the alignment is contained +in a vertical box, lines above and below the alignment +can be specified with +\begin{verbatim} +\vbox{\hrule \halign{...} \hrule} +\end{verbatim} +The most general way to get horizontal lines in an alignment +is to use +\cstoidx multispan\par +\begin{disp}\cs{multispan}$\,n$\cs{hrulefill}\end{disp} +which can be used to underline arbitrary adjacent columns. + +Vertical rules in alignments take some more care. +Since a horizontal alignment breaks up into +horizontal boxes that will be placed on a vertical list, +\TeX\ will insert baselineskip glue in between the rows +of the alignment. If vertical rules in adjacent rows +are to abut, it is necessary to prevent baselineskip glue, +for instance by the \cs{offinterlineskip} macro. + +In order to ensure that rows will still be properly spaced +it is then necessary to place a {\italic strut\/} +somewhere in the preamble. +A~strut is an invisible object with a certain height +and depth. Putting that in the preamble guarantees that +every line will have at least that height and depth. +In the plain format \csidx{strut} is +defined statically as +\begin{verbatim} +\vrule height8.5pt depth3.5pt width0pt +\end{verbatim} +so this must be changed when other fonts or sizes are used. + +It is a good idea to use a whole column for a~vertical +rule, that is, to write +\begin{verbatim} +\vrule#& +\end{verbatim} +in the preamble and +to leave the corresponding entry in the alignment empty. +Omitting the vertical rule can then be done by specifying \cs{omit}, +and the size of the rule can be specified explicitly by +putting, for instance, +\hbox{\n{height 15pt}} in the entry instead of leaving +it empty. Of course, tabskip glue will now be specified to the +left and right of the rule, so some extra tabskip assignments +may be needed in the preamble. + +%\spoint End of a line: \cs{cr} and \cs{crcr} +\subsection{End of a line: \cs{cr} and \cs{crcr}} + +All lines in an alignment are terminated by the \csidx{cr} control +sequence, including the last line. +\TeX\ is not able to infer from +a closing brace in the $\alpha$~part that the +alignment has ended, because an unmatched +closing brace is perfectly valid in +an alignment entry; it may match an opening brace in +the $u$~part of the corresponding preamble entry. + +\TeX\ has a primitive command \csidx{crcr} that is equivalent +to \cs{cr}, but it has no effect if it immediately follows +a~\cs{cr}. +Consider as an example the definition in plain \TeX\ +of \csidx{cases}: +\begin{verbatim} +\def\cases#1{% + \left\{\,\vcenter{\normalbaselines\m@th + \ialign{ $##\hfil$& \quad##\hfil \crcr #1\crcr}}% + \right.} +\end{verbatim} +Because of the \cs{crcr} after the user argument \verb.#1., +the following two applications of this macro +\begin{disp}\verb>\cases{1&2\cr 3&4}>\quad and\quad \verb>\cases{1&2\cr 3&4\cr}>\end{disp} +both work. In the first case the \cs{crcr} in the macro +definition ends the last line; +in the second case the user's \cs{cr} ends the line, +and the \cs{crcr} is redundant. + +After \cs{cr} and after a non-redundant \cs{crcr} the +\gr{token parameter} \csidx{everycr} is inserted. +This includes the \cs{cr} terminating the template line. + +%\point Example: math alignments +\section{Example: math alignments} + +The plain format has several alignment macros that function +in math mode. One example is \csidx{matrix}, defined by +\begin{verbatim} +\def\matrix#1{\null\,\vcenter{\normalbaselines\m@th + \ialign{\hfil$##$\hfil && \quad\hfil$##$\hfil\crcr + \mathstrut\crcr + \noalign{\kern-\baselineskip} + #1\crcr + \mathstrut\crcr + \noalign{\kern-\baselineskip}}}\,} +\end{verbatim} +This uses a repeating (starting with~\verb>&&>) second preamble entry; +each entry is centred by an \cs{hfil} before and after it, +and there is a \cs{quad} of space in between columns. +Tabskip glue was not used for this, because there should not +be any glue preceding or following the matrix. + +The combination of a \cs{mathstrut} and \verb>\kern-\baselineskip> +above and below the matrix increases the vertical size +such that two matrices with the same number of rows will have +the same height and depth, which would not otherwise be the case +if one of them had subscripts in the last row, but the other +not. The \cs{mathstrut} causes interline glue to be inserted +and, because it has a size equal to \cs{baselineskip}, +the negative kern will effectively leave only the interline glue, +thereby buffering any differences in the first and last line. +Only to a certain point, of course: objects bigger than the +opening brace will still result in a different height or depth of the +matrix. + +Another, more +complicated, example of an alignment for math mode is \cs{eq\-alignno}. +\cstoidx eqalignno\par\cstoidx centering\par +\begin{verbatim} +\def\eqalignno#1{\begin{disp}l@y \tabskip\centering + \halign to\displaywidth{ + \hfil$\@lign\displaystyle{##}$% -- first column + \tabskip\z@skip + &$\@lign\displaystyle{{}##}$\hfil% -- second column + \tabskip\centering + &\llap{$\@lign##$}% -- third column + \tabskip\z@skip\crcr % end of the preamble + #1\crcr}} +\end{verbatim} +Firstly, the tabskip is set to zero after the equation +number, so this number is set flush with the right margin. +Since it is placed by \cs{llap}, its effective width +is zero. Secondly, the tabskip between the +first and second columns is also zero, and the tabskip +before the first column and after the second is +\alt +\cs{centering}, which is \n{0pt plus 1000pt minus 1000pt}, +so the first column and second are jointly centred +in the \cs{hsize}. Note that, because of the +\n{minus 1000pt}, these two columns will happily go +outside the left and right margins, overwriting any +equation numbers. + + +% \begin{comment} +% \endinput +% %\spoint Error messages +% \subsection{Error messages} + +% \aftergroup in alignment? + +% \end{comment} +%%%% end of input file [align] + +%\InputFile:page +%%%% this is input file [page] +%\subject[page:shape] Page Shape +\endofchapter +\chapter{Page Shape}\label{page:shape} + +This chapter treats some of the parameters that +determine the size of the page and how it appears on paper. + +\begin{inventory} +\item [\cs{topskip}] + Minimum distance between the top of the page box + and the baseline of the first box on the page. + Plain \TeX\ default:~\n{10pt} + +\item [\cs{hoffset \cs{voffset}}] +\mdqon + Distance by which the page is shifted right/""down +\mdqoff + with respect to the reference point. + +\item [\cs{vsize}] + Height of the page box. + Plain \TeX\ default:~\n{8.9in} + +\item [\cs{maxdepth}] + Maximum depth of the page box. + Plain \TeX\ default:~\n{4pt} + +\item [\cs{splitmaxdepth}] + Maximum depth of a box split off by a \cs{vsplit} operation. + Plain \TeX\ default:~\cs{maxdimen} + +\end{inventory} + +%\point The reference point for global positioning +\section{The reference point for global positioning} + +It is a \TeX\ convention, to which output device drivers +\term page positioning\par +must adhere, that the top left point of the page is +one inch from the page edges. Unfortunately this +may lead to lots of trouble, for instance if a printer +(or the page description language it uses) +takes, say, the {\em lower\/} left corner as the +reference point, and is factory set to US paper sizes, +but is used with European standard A4 paper. + +The page is shifted on the paper if one assigns non-zero +values to \csidx{hoffset} or \csidx{voffset}: positive values +shift to the right and down respectively. + +%\point \cs{topskip} +\section{\protect\cs{topskip}} + +The \csidx{topskip} ensures to a certain point +that the first baseline of a page +will be at the same location from page to page, +even if font sizes +are switched between pages or if the first line has +no ascenders. + +Before the first box on each page some glue is inserted. +This glue has the same stretch and shrink as \cs{topskip}, but +the natural size is the natural size of \cs{topskip} +minus the height of the first box, or zero if this +would be negative. + +Plain \TeX\ sets \cs{topskip} to {\tt 10pt}. +Thus the top lines of pages will have their baselines +at the same place if +the top portion of the characters is ten point or less. +For the Computer Modern fonts this condition is satisfied +if the font size is less than (about) 13~points; +for larger fonts +the baseline of the top line will drop. + +The height of the page box for a page containing only +text (and assuming a zero \cs{parskip}) +will be the \cs{topskip} plus a number of times +the \cs{baselineskip}. Thus one can define a macro +to compute the \cs{vsize} from the number of lines +on a page: +\howto Specify page height in lines\par +\begin{verbatim} +\def\HeightInLines#1{\count@=#1\relax + \advance\count@ by -1\relax + \vsize=\baselineskip + \multiply\vsize by \count@ + \advance\vsize by \topskip} +\end{verbatim} +Calculating the \cs{vsize} this way will prevent +underfull boxes for text-only pages. + +In cases where the page does not start with a line of text +(for instance a rule), the topskip may give unwanted effects. +To prevent these, start the page with +\begin{verbatim} +\hbox{}\kern-\topskip +\end{verbatim} +followed by what you wanted on top. + +Analogous to the \cs{topskip}, there is a \cs{splittopskip} +for pages generated by a \cs{vsplit} operation; see +the next chapter. + +%\point Page height and depth +\section{Page height and depth} + +\TeX\ tries to build pages as a \cs{vbox} of height \csidx{vsize}; +\alt +see also \cs{pagegoal} in the next chapter. + +If the last item on a page has an excessive depth, +\term page depth\par +that page would be noticeably longer than other pages. +To prevent this phenomenon \TeX\ uses \csidx{maxdepth} as +the maximum depth of the page box. If adding an item to the +page would make the depth exceed this quantity, then the +reference point of the page is moved down to make the depth +exactly \cs{maxdepth}. + +The `raggedbottom' effect is obtained in plain \TeX\ +\cstoidx raggedbottom\par +by giving the \cs{topskip} some finite stretchability: +\hbox{\n{10pt plus 60pt}}. +Thus the natural height of box~255 can vary when it reaches +the output routine. +Pages are then shipped out (more or less) as +\begin{verbatim} +\dimen0=\dp255 \unvbox255 +\ifraggedbottom \kern-\dimen0 \vfil \fi +\end{verbatim} +The \cs{vfil} causes the topskip to be set at natural +width, so the effect is one of a fixed top line and a +variable bottom line of the page. + +Before \cs{box255} is unboxed in the plain \TeX\ output routine, +\cs{boxmaxdepth} is set to \cs{maxdepth} +so that this box will made under the same assumptions +that the page builder used when putting together \cs{box255}. + +The depth of box split off by a \cs{vsplit} operation +is controlled by the \cs{splitmaxdepth} parameter. + +%\subject[page:break] Page Breaking +\endofchapter +\chapter{Page Breaking}\label{page:break} + +This chapter treats the `page builder': the part of \TeX\ +that decides where to break the main vertical list into pages. +The page builder operates before the output routine, +and it hands its result in \cs{box255} to the output routine. + +\begin{inventory} +\item [\cs{vsplit}] + Split of a top part of a box. This is comparable + with page breaking. + +\item [\cs{splittopskip}] + Minimum distance between the top of what remains after a + \cs{vsplit} operation, and the first item in that box. + Plain \TeX\ default:~\n{10pt} + +\item [\cs{pagegoal}] + Goal height of the page box. This starts at \cs{vsize}, + and is diminished by heights of insertion items. + +\item [\cs{pagetotal}] + Accumulated natural height of the current page. + +\item [\cs{pagedepth}] + Depth of the current page. + +\item [\cs{pagestretch}] + Accumulated zeroth-order stretch of the current page. + +\item [\cs{pagefilstretch}] + Accumulated first-order stretch of the current page. + +\item [\cs{pagefillstretch}] + Accumulated second-order stretch of the current page. + +\item [\cs{pagefilllstretch}] + Accumulated third-order stretch of the current page. + +\item [\cs{pageshrink}] + Accumulated shrink of the current page. + +\item [\cs{outputpenalty}] + Value of the penalty at the current page break, + or $10\,000$ if the break was not at a penalty. + +\item [\cs{interlinepenalty}] + Penalty for breaking a page between lines of a paragraph. + Plain \TeX\ default:~\n{0} + +\item [\cs{clubpenalty}] + Additional penalty for breaking a page after + the first line of a paragraph. + Plain \TeX\ default:~\n{150} + +\item [\cs{widowpenalty}] + Additional penalty for breaking a page before + the last line of a paragraph. + Plain \TeX\ default:~\n{150} + +\item [\cs{displaywidowpenalty}] + Additional penalty for breaking a page before the last line + above a display formula. + Plain \TeX\ default:~\n{50} + +\item [\cs{brokenpenalty}] + Additional penalty for breaking a page after a hyphenated line. + Plain \TeX\ default:~\n{100} + +\item [\cs{penalty}] + Place a penalty on the current list. +\item [\cs{lastpenalty}] + If the last item on the list was a penalty, the value of this. +\item [\cs{unpenalty}] + Remove the last item of the current list if this + was a penalty. + +\end{inventory} + +%\point The current page and the recent contributions +\section{The current page and the recent contributions} + +The main vertical list of \TeX\ is divided in two parts: +\term current page\par\term recent contributions\par +\term page builder\par +the `current page' and the list of `recent contributions'. +Any material that is added to the main vertical list is +appended to the recent contributions; the act of moving +the recent contributions to the current page is known +as `exercising the page builder'. + +Every time something is moved to the current page, \TeX\ +computes the cost of breaking the page at that point. +If it decides that it is past the optimal point, +the current page up to +\altt +the best break so far +is put in \cs{box255} and the remainder of +the current page is moved back on top of the recent contributions. +If the page is broken at a penalty, +\label{break:penalty}% +that value is recorded in \cs{outputpenalty}, and +a penalty of size $10\,000$ is placed on top of the +recent contributions; otherwise, \csidx{outputpenalty} +is set to~$10\,000$. + +If the current page is empty, discardable items that are moved +from the recent contributions are discarded. This is the mechanism +that lets glue disappear after a page break and at the top of +the first page. When the first non-discardable item is moved +to the current page, the \cs{topskip} glue is inserted; +see the previous chapter. + +The workings of the page builder can be made visible by +setting \cs{tracingpages} to some positive value +(see Chapter~\ref{trace}). + +%\point Activating the page builder +\section{Activating the page builder} + +The page builder comes into play in the +following circumstances. +\begin{itemize}\item Around paragraphs: after the \cs{everypar} + tokens have been inserted, and after the paragraph has been + added to the vertical list. See the end of this chapter for + an example. +\item Around display formulas: after the \cs{everydisplay} + tokens have been inserted, and after the display has been + added to the list. +\item After \cs{par} commands, boxes, insertions, + and explicit penalties in vertical mode. +\item After an output routine has ended. \end{itemize} +In these places the page builder moves the recent +contributions to the current page. Note that \TeX\ need not be +in vertical mode when the page builder is exercised. +In horizontal mode, activating the page builder +serves to move preceding vertical glue (for example, \cs{parskip}, +\cs{abovedisplayskip}) to the page. + +The \cs{end} command \ldash which is only allowed in +external vertical mode \rdash terminates a \TeX\ job, but only if the +main vertical list is empty and \cs{deadcycles}${}=0$. +If this is not the case the combination +\label{end:play}% +\begin{disp}\verb>\hbox{}\vfill\penalty>$-2^{30}$\end{disp} +is appended, which forces the output routine to act. + +%\point Page length bookkeeping +\section{Page length bookkeeping} + +The height and depth of the page box that reaches the output +\term page length\par +routine are determined by \cs{vsize}, \cs{topskip}, +and~\cs{maxdepth} as described in the previous chapter. +\TeX\ places the \cs{topskip} glue +when the first box is placed on the current page; the +\cs{vsize} and \cs{maxdepth} are read when the first +box or insertion occurs on the page. Any subsequent changes to these +parameters will not be noticeable until the next page or, +more strictly, until after the output routine has been called. + +After the first box, rule, or insertion on the current page +the \cs{vsize} is recorded in \cs{pagegoal}, +and its value is not looked at until \cs{output} +has been active. +Changing \cs{pagegoal} does have an effect on the current +page. +When the page is empty, +the pagegoal is \cs{maxdimen}, and \cs{pagetotal} is zero. + +Accumulated dimensions and stretch are available in +the parameters \cs{pagetotal}, \cs{pagedepth}, +\cs{pagestretch}, \cs{pagefilstretch}, \cs{pagefillstretch}, +\cs{pageshrink}, +and \cs{pagefilllstretch}. +\cstoidx pagetotal\par\cstoidx pagedepth\par +\cstoidx pagestretch\par\cstoidx pagefilstretch\par +\cstoidx pagefillstretch\par +\cstoidx pageshrink\par\cstoidx pagefilllstretch\par +They are set by the page builder. The stretch and +shrink parameters are updated every time glue is added +to the page. The depth parameter becomes zero +if the last item was kern or glue. + +These parameters are \gr{special dimen}s; an assignment +to any of them is an \gr{intimate assignment}, +and it is automatically global. + +%\point Breakpoints +\section{Breakpoints} + +%\spoint Possible breakpoints +\subsection{Possible breakpoints} + +Page breaks can occur at the same kind of locations where +\term breakpoints in vertical lists\par +line breaks can occur: +\begin{itemize}\item at glue that is preceded by a non-discardable +item;\item at a kern that is immediately followed by glue; +\item at a penalty.\end{itemize} +\TeX\ inserts interline glue and various sorts of +interline penalties when the lines of a paragraph are +added to the vertical list, so there will usually be +sufficient breakpoints on the page. + +%\spoint Breakpoint penalties +\subsection{Breakpoint penalties} + +If \TeX\ decides to break a page at a penalty item, this +penalty will, most of the time, be one that +has been inserted automatically +between the lines of a paragraph. + +If the last item on a list (not necessarily a vertical list) +\alt +is a penalty, the value of this is recorded +in the parameter \csidx{lastpenalty}. If the item is other than +a penalty, this parameter has the value zero. +The last penalty of a list can be removed with the command +\csidx{unpenalty}. See Section~\ref{varioset} for an example. +\message{Spoint ref varioset} + +Here is a list of such penalties\term penalties in vertical mode\par: +\begin{inventory} +\item [\csidx{interlinepenalty}] + Penalty for breaking a page between lines of a paragraph. + In plain \TeX\ this is zero, so no penalty is added in + between lines. \TeX\ can then find a valid breakpoint at the + \cs{baselineskip} glue. + +\item [\csidx{clubpenalty}] + Extra penalty for breaking a page after the first line of a paragraph. + In plain \TeX\ this is~\n{150}. + This amount, and the following penalties, are + added to the \cs{interlinepenalty}, and + a penalty of the resulting size is inserted after the + \cs{hbox} containing the first line of a paragraph + instead of the \cs{interlinepenalty}. + +\item [\csidx{widowpenalty}] + Extra penalty for breaking a page before the last line of a paragraph. + In plain \TeX\ this is~\n{150}. + +\item [\csidx{displaywidowpenalty}] + Extra penalty for breaking a page before the last line + above a display formula. The default value in plain \TeX\ + is~\n{50}. + +\item [\csidx{brokenpenalty}] + Extra penalty for breaking a page after a hyphenated line. + The default value in plain \TeX\ is~\n{100}. +\end{inventory} +If the resulting penalty is zero, it is not placed. + +Penalties can also be inserted by the user. For instance, +the plain format has macros to encourage (possibly, force) +or prohibit page breaks\cstoidx penalty\par: +\begin{verbatim} +\def\break{\penalty-10000 } % force break +\def\nobreak{\penalty10000 } % prohibit break +\def\goodbreak{\par\penalty-500 } % encourage page break +\end{verbatim} +Also, \verb>\vadjust{\penalty ... }> is a way of getting +penalties in the vertical list. This can be used to +discourage or encourage page breaking after a certain +line of a paragraph. + +%\spoint Breakpoint computation +\subsection{Breakpoint computation} + +\advance\rightskip by 5.5cm + +Whenever an item is moved to the current page, \TeX\ +\term page breaking\par\term breakpoints, computation of\par +\vadjust{\advance\hsize by -5.5cm + \hbox to \hsize{\hfil\rlap{\hskip.4cm\vtop to 0pt + {\kern-2\baselineskip + \SansSerif %\pointSize:8 \Style:roman + \parindent0pt \offinterlineskip + \def\tbox#1{\hbox{\quad\quad #1% + \vrule height 10pt depth3pt width0cm }} + \hbox + {\vrule width\lw \kern-\lw + \vbox{\hsize=5cm + \hrule height\lw \ \vskip0cm + \kern40pt + \tbox{underfull page} + \tbox{$b=10\,000$} + \kern40pt + \hrule height\lw + \kern8pt + \tbox{feasible breakpoints} + \tbox{$b<10\,000$} + \kern8pt + \hrule height\lw + \kern8pt + \tbox{overfull page} + \tbox{$b=\infty$} + \kern3pt + \tbox{.\vrule height3.5pt depth1pt width0cm} + \tbox{.\vrule height3.5pt depth1pt width0cm} + \tbox{.\vrule height3.5pt depth1pt width0cm} + \kern8pt + }% + \kern-\lw \vrule width\lw}% + \vss}}}} +computes the penalty $p$ and the badness $b$ associated with +breaking the page at that place. From the penalty and +the badness the cost $c$ of breaking is computed. + +The place of least cost is remembered, and when +the cost is infinite, that is, the page is overfull, or +when the penalty is $p\leq-10\,000$, the current page is broken +at the (last remembered) place of least cost. +The broken-off piece is then +put in \cs{box255} and the output routine token list +is inserted. Box 255 is always given a height of \cs{vsize}, +regardless of how much material it has. + +The badness calculation is based on the amount of stretching +or shrinking that is necessary to fit the page in +a box with height \cs{vsize} +and maximum depth \cs{maxdepth}. This calculation is +the same as for line breaking (see Chapter~\ref{glue}). +Badness is a value $0\leq b\leq 10\,000$, except when +pages are overfull; then~$b=\infty$. + +\advance\rightskip by -5.5cm + +Some penalties are implicitly inserted by \TeX, +for instance the \cs{interlinepenalty} +which is put in between every pair of lines of a paragraph. +Other penalties can +be explicitly inserted by the user or a user macro. +A~penalty +value $p\geq10\,000$ inhibits breaking; a penalty +$p\leq-10\,000$ (in external vertical mode) +\alt +forces a page break, and immediately +activates the output routine. + +Cost calculation proceeds as follows: +\begin{enumerate} \item When a penalty is so low that it forces +a page break and immediate invocation of the output routine, +but the page is not overfull, that is +\begin{disp}$b<\infty\quad\hbox{and}\quad p\leq-10\,000$\end{disp} +the cost is equal to the penalty:~$c=p$. + +\item When penalties do not force anything, and the page is not +overfull, that is +\begin{disp}$b<\infty\quad\hbox{and}\quad |p|<10\,000$\end{disp} +the cost is~$c=b+p$. + +\item For pages that are very bad, that is +\begin{disp}$b=10\,000\quad\hbox{and}\quad |p|<10\,000$\end{disp} +the cost is~$c=10\,000$. + +\item An overfull page, that is +\begin{disp}$b=\infty\quad\hbox{and}\quad p<10\,000$\end{disp} +gives infinite cost:~$c=\infty$. +In this case \TeX\ decides that the optimal break point +must have occurred earlier, and it invokes the output routine. +Values of \cs{insertpenalties} (see Chapter~\ref{insert}) +that exceed $10\,000$ +also give infinite cost. +\end{enumerate} + +The fact that a penalty $p\leq-10\,000$ activates +the output routine is used extensively +in the \LaTeX\ output routine: +the excess $\mathopen|p\mathclose|-10\,000$ is +a code indicating the reason for calling the output routine; +see also the second example in the next chapter. + +%\point[vsplit] \cs{vsplit} +\section{\protect\cs{vsplit}} +\label{vsplit} + +The page-breaking operation is available to the user +through the \csidx{vsplit} operation. + +\begin{example} \begin{verbatim} +\setbox1 = \vsplit2 to \dimen3 +\end{verbatim} +assigns to box~1 the top part of size \cs{dimen3} +of box~2. This material is actually removed from box~2. +Compare this with splitting off a chunk of size \cs{vsize} +from the current page. +\end{example} + +The extracted +result of \begin{disp}\cs{vsplit}\gr{8-bit number}\n{to}\gr{dimen} +\end{disp} is a box with the following properties. +\begin{itemize} \item Height equal to the specified \gr{dimen}; \TeX\ will + go through the original box register (which must contain + a vertical box) to find the best breakpoint. This may + result in an underfull box. +\item Depth at most \csidx{splitmaxdepth}; this is analogous to + the \cs{maxdepth} for the page box, rather than the \cs{boxmaxdepth} + that holds for any box. +\item A first and last mark in the \cs{splitfirstmark} and + \cs{splitbotmark} registers. +\end{itemize} + +The remainder of the \cs{vsplit} operation is a box where +\begin{itemize} \item all discardables have been removed + from the top; +\item glue of size \csidx{splittopskip} has been inserted on top; + if the box being split was box~255, it + already had \cs{topskip} glue on top; +\item its depth has been forced to be at most \cs{splitmaxdepth}. +\end{itemize} + +The bottom of the original box is always a valid breakpoint +for the \cs{vsplit} operation. If this breakpoint is taken, +the remainder box register is void. The extracted box +can be empty; it is only void if the original box +was void, or not a vertical box. + +Typically, the \cs{vsplit} operation is used to split off part +of \cs{box255}. By setting \cs{splitmaxdepth} equal to \cs{boxmaxdepth} +the result is something that could have been made by \TeX's page +builder. After pruning the top of \cs{box255}, the +mark registers \cs{firstmark} and \cs{botmark} contain the first +and last marks on the remainder of box~255. +See the next chapter for more information on marks. + +%\point Examples of page breaking +\section{Examples of page breaking} + +%\spoint Filling up a page +\subsection{Filling up a page} + +Suppose a certain vertical box is too large +to fit on the remainder of the page. +Then \begin{verbatim} +\vfil\vbox{ ... } +\end{verbatim} +is the wrong way +to fill up the page and push the box to the next. +\TeX\ can only break at the start of the glue, and +the \cs{vfil} is discarded after the break: the result +is an underfull, or at least horribly stretched, page. +On the other hand, +\begin{verbatim} +\vfil\penalty0 % or any other value +\vbox{ ... } +\end{verbatim} +is the correct way: \TeX\ will break +at the penalty, and the page will be filled. + +%\spoint Determining the breakpoint +\subsection{Determining the breakpoint} + +In the following examples the \cs{vsplit} operation is +used, which has the same +mechanism as page breaking. + +Let the macros and +parameter settings +\begin{verbatim} +\offinterlineskip \showboxdepth=1 +\def\High{\hbox{\vrule height5pt}} +\def\HighAndDeep{\hbox{\vrule height2.5pt depth2.5pt}} +\end{verbatim} +be given. + +First let us consider +an example where a vertical list is simply stretched +in order to reach a break point. +\begin{verbatim} +\splitmaxdepth=4pt +\setbox1=\vbox{\High \vfil \HighAndDeep} +\setbox2=\vsplit1 to 9pt +\end{verbatim} +gives \begin{verbatim} +> \box2= +\vbox(9.0+2.5)x0.4, glue set 1.5fil +.\hbox(5.0+0.0)x0.4 [] +.\glue 0.0 plus 1.0fil +.\glue(\lineskip) 0.0 +.\hbox(2.5+2.5)x0.4 [] +\end{verbatim} +The two boxes together have a height of \n{7.5pt}, +so the glue has to stretch~\n{1.5pt}. + +Next, we decrease the allowed depth of the resulting list. +\begin{verbatim} +\splitmaxdepth=2pt +\setbox1=\vbox{\High \vfil \HighAndDeep} +\setbox2=\vsplit1 to 9pt +\end{verbatim} +gives +\begin{verbatim} +> \box2= +\vbox(9.0+2.0)x0.4, glue set 1.0fil +.\hbox(5.0+0.0)x0.4 [] +.\glue 0.0 plus 1.0fil +.\glue(\lineskip) 0.0 +.\hbox(2.5+2.5)x0.4 [] +\end{verbatim} +The reference point is moved down half a point, +and the stretch is correspondingly diminished, +\alt +but this motion cannot lead to a larger dimension +than was specified. + +As an example of this, +\alt +consider the sequence \begin{verbatim} +\splitmaxdepth=3pt +\setbox1=\vbox{\High \kern1.5pt \HighAndDeep} +\setbox2=\vsplit1 to 9pt +\end{verbatim} +This gives a box exactly 9 points high and 2.5 points deep. +Setting \verb>\splitmaxdepth=2pt> does not increase +the height by half a point; instead, an underfull box +results because an earlier break is taken. + +Sometimes the timing of actions is important. +\TeX\ first locates a breakpoint that will lead +to the requested height, then checks whether accommodating +the \cs{maxdepth} or \cs{splitmaxdepth} will not +violate that height. + +Consider an example of this timing: +\alt +in +\begin{verbatim} +\splitmaxdepth=4pt +\setbox1=\vbox{\High \vfil \HighAndDeep} +\setbox2=\vsplit1 to 7pt +\end{verbatim} +the result is {\italic not\/} a box +of 7 points high and 3 points deep. Instead, +\begin{verbatim} +> \box2= +\vbox(7.0+0.0)x0.4 +.\hbox(5.0+0.0)x0.4 [] +\end{verbatim} +which is an underfull box. + +%\spoint[par:page:build] The page builder after a paragraph +\subsection{The page builder after a paragraph} +\label{par:page:build} + +After a paragraph, the page builder moves material +to the current page, but it does not decide whether a breakpoint +has been found yet. + +\begin{example}\begin{verbatim} +\output{\interrupt \plainoutput}% show when you're active +\def\nl{\hfil\break}\vsize=22pt % make pages of two lines +a\nl b\nl c\par \showlists % make a 3-line paragraph +\end{verbatim} +will report +\begin{verbatim} +### current page: +[...] +total height 34.0 + goal height 22.0 +prevdepth 0.0, prevgraf 3 lines +\end{verbatim} +Even though more than enough +material has been gathered, \cs{output} is only invoked +when the next paragraph starts: typing a \n d gives +\begin{verbatim} +! Undefined control sequence. +<output> {\interrupt + \plainoutput } +<to be read again> + d +\end{verbatim} +when \cs{output} is inserted after \cs{everypar}. +\end{example} + +%\subject[output] Output Routines +\endofchapter +\chapter{Output Routines}\label{output} + +The final stages of page processing are performed by the +output routine. The page builder cuts off a certain portion +of the main vertical list and hands it to the output routine +in \cs{box255}. This chapter treats the commands and parameters +that pertain to the output routine, and it explains how +output routines can receive information through marks. + +\begin{inventory} +\item [\cs{output}] + Token list with instructions for shipping out pages. + +\item [\cs{shipout}] + Ship a box to the \n{dvi} file. + + +\item [\cs{mark}] + Specify a mark text. + +\item [\cs{topmark}] + The last mark on the previous page. + +\item [\cs{botmark}] + The last mark on the current page. + +\item [\cs{firstmark}] + The first mark on the current page. + +\item [\cs{splitbotmark}] + The last mark on a split-off page. + +\item [\cs{splitfirstmark}] + The first mark on a split-off page. + +\item [\cs{deadcycles}] + Counter that keeps track of how many times + the output routine has been called without a \cs{shipout} + taking place. + +\item [\cs{maxdeadcycles}] + The maximum number of times that the output routine is allowed to + be called without a \cs{shipout} occurring. + +\item [\cs{outputpenalty}] + Value of the penalty at the current page break, + \alt + or $10\,000$ if the break was not at a penalty. + +\end{inventory} + + +%\point The \cs{output} token list +\section{The \protect\cs{output} token list} + +Common parlance has it that +`the output routine is called' when \TeX\ has found a place +to break the main vertical list. +Actually, \cs{output} is not a macro but a token list that +is inserted into \TeX's command stream. + +Insertion of the \cs{output} token list happens +\cstoidx output\par\term output routine\par +inside a group that is implicitly opened. +Also, \TeX\ enters internal vertical mode. +Because of the group, non-local assignments +(to the page number, for instance) +have to be prefixed with \cs{global}. +The vertical mode implies that during the workings of the +output routine +spaces are mostly harmless. + +The \cs{output} token list belongs +to the class of the +\gr{token parameter}s. These behave the same as +\cs{toks}$nnn$ token lists; see Chapter~\ref{token}. +Assigning an output routine can therefore take the following +forms: +\begin{disp}\cs{output}\gr{equals}\gr{general text}\quad +or\quad +\cs{output}\gr{equals}\gr{filler}\gr{token variable} +\end{disp} + + +%\point[output255] Output and \cs{box255} +\section{Output and \protect\cs{box255}} +\label{output255} + +\TeX's page builder breaks the current page at the optimal point, +and stores everything above that in \cs{box255}; +then, the \cs{output} tokens are inserted into the input stream. +Any remaining material on the main vertical list +is pushed back to the recent +contributions. +If the page is broken at a penalty, +\alt +that value is recorded in \cs{outputpenalty}, and +a penalty of size $10\,000$ is placed on top of the +recent contributions; otherwise, \cs{outputpenalty} +is set to~$10\,000$. +When the output routine is finished, \cs{box255} is +supposed to be empty. +If it is not, \TeX\ gives an error message. + +Usually, the output routine will take the pagebox, +\cstoidx shipout\par +\mdqon +append a headline and/""or footline, +\mdqoff +maybe merge in some insertions such as footnotes, +and ship the page to the \n{dvi} file: +\begin{verbatim} +\output={\setbox255=\vbox + {\someheadline + \vbox to \vsize{\unvbox255 \unvbox\footins} + \somefootline} + \shipout\box255} +\end{verbatim} +When box 255 reaches the output routine, its height has +been set to \cs{vsize}. +However, the material in it can have considerably +smaller height. +Thus, the above output routine may lead to underfull boxes. +This can be remedied with a \cs{vfil}. + +The output routine is under no obligation to +\cstoidx deadcycles\par +do anything useful with \cs{box255}; it can empty it, or +unbox it to let \TeX\ have another go at finding a page +break. The number of times +that the output routing postpones the \cs{shipout} +is recorded in \cs{deadcycles}: this parameter is set to~0 +by \cs{shipout}, and increased by~1 just before +every \cs{output}. + +When the number of dead cycles reaches +\csidx{maxdeadcycles}, \TeX\ gives an error message, +and performs the default output routine +\begin{verbatim} +\shipout\box255 +\end{verbatim} +instead of the routine it was about +to start. +The \LaTeX\ format has a much higher value for \cs{maxdeadcycles} +than plain \TeX, because the output routine in \LaTeX\ +is often called for +intermediate handling of floats and marginal notes. + +The \cs{shipout} command can send any \gr{box} to the \n{dvi} file; +this need not be box 255, or even a box +containing the current page. +It does not have to be called inside the output routine, either. + +If the output routine produces any material, for instance +by calling \begin{verbatim} +\unvbox255 +\end{verbatim} +this is put on top +of the recent contributions. + +After the output routine finishes, the page builder is +activated. In particular, because the current page +has been emptied, the \cs{vsize} is read again. +Changes made to this parameter inside the output +routine (using \cs{global}) will therefore take effect. + +%\point Marks +\section{Marks} + +Information can be passed to the output routine through the +\term marks\par\cstoidx mark\par +mechanism of `marks'. The user can specify a token list +with \begin{disp}\cs{mark}\lb\gr{mark text}\rb\end{disp} +which is put in a mark item on the current vertical list. +The mark text is subject to expansion as in \cs{edef}. + +If the mark is given in horizontal mode it migrates to +the surrounding vertical lists like an insertion item +(see page~\pageref{migrate}); +however, if this is not the external vertical list, the +output routine will not find the mark. + +Marks are the main mechanism through which the output routine +can obtain information about the contents of the currently +broken-off page, in particular its top and bottom. +\TeX\ sets three variables: +\begin{description} +\item [\csidx{botmark}] + the last mark occurring on the current page; +\item [\csidx{firstmark}] + the first mark occurring on the current page; +\item [\csidx{topmark}] + the last mark of the previous page, + that is, the value of \cs{botmark} + on the previous page. +\end{description} +If no marks have occurred yet, all three are empty; +if no marks occurred on the current page, +all three mark variables are equal +to the \cs{botmark} of the previous page. + +For boxes generated by a \cs{vsplit} command (see previous chapter), +the \cs{splitbotmark} and \cs{splitfirstmark} +\cstoidx splitbotmark\par\cstoidx splitfirstmark\par +contain the marks of the split-off part; \cs{firstmark} +and \cs{botmark} reflect the state of what remains in the register. + +\begin{example} Marks can be used to get a section heading into +\howto Do tricks with headlines\par +the headline or footline of the page. +\begin{verbatim} +\def\section#1{ ... \mark{#1} ... } +\def\rightheadline{\hbox to \hsize + {\headlinefont \botmark\hfil\pagenumber}} +\def\leftheadline{\hbox to \hsize + {\headlinefont \pagenumber\hfil\firstmark}} +\end{verbatim} +This places the title of the first section that starts on a +left page in the left headline, and the title of the last section +that starts on the right page in the right headline. +Placing the headlines on the page is the job of the output routine; +see below. + +It is important that no page breaks can occur in between the +mark and the box that places the title: +\begin{verbatim} +\def\section#1{ ... + \penalty\beforesectionpenalty + \mark{#1} + \hbox{ ... #1 ...} + \nobreak + \vskip\aftersectionskip + \noindent} +\end{verbatim} +\end{example} + +Let us consider +another example with headlines: often a page looks better if +the headline is omitted on pages where a chapter starts. +This can be implemented as follows: +\begin{verbatim} +\def\endofchapter +\chapter#1{ ... \def\chtitle{#1}\mark{1}\mark{0} ... } +\def\theheadline{\expandafter\ifx\firstmark1 + \else \chapheadline \fi} +\end{verbatim} +Only on the page where a chapter starts will the mark be~1, +and on all other pages a headline is placed. + +%\point Assorted remarks +\section{Assorted remarks} + +%\spoint Hazards in non-trivial output routines +\subsection{Hazards in non-trivial output routines} + +If the final call to the output routine does not +perform a \cs{shipout}, \TeX\ will call the output +routine endlessly, since a run will only stop if both +the vertical list is empty, and \cs{deadcycles} +is zero. The output routine can set \cs{deadcycles} +to zero to prevent this. + +%\spoint Page numbering +\subsection{Page numbering} + +The page number is not an intrinsic property of the output +\term page numbering\par +routine; in plain \TeX\ it is the value of \cs{count0}. +The output routine is responsible for increasing the +page number when a shipout of a page occurs. + +Apart from \cs{count0}, counter registers~1--9 are also used +for page identification: at shipout \TeX\ writes the values +of these ten counters to the \n{dvi} file (see Chapter~\ref{TeXcomm}). +Terminal and log file output display only the non-zero counters, +and the zero counters for which a non-zero counter with +a higher number exists, that is, if \cs{count0}${}=1$ and +\cs{count3}${}=5$ are the only non-zero counters, the +displayed list of counters is~\n{[1.0.0.5]}. + +%\spoint Headlines and footlines in plain \TeX\ +\subsection{Headlines and footlines in plain \TeX} + +Plain \TeX\ has token lists \cs{headline} and +\cs{footline}; these are used in the macros +\cs{makeheadline} and \cs{makefootline}. +The page is shipped out as (more or less) +\begin{verbatim} +\vbox{\makeheadline\pagebody\makefootline} +\end{verbatim} + +Both headline and footline are inserted inside a \cs{line}. +For non-standard headers and footers it is easier to +redefine the macros \cs{makeheadline} and \cs{makefootline} +than to tinker with the token lists. + +%\spoint Example: no widow lines +\subsection{Example: no widow lines} + +Suppose that one does not want to allow widow lines, +but pages have in general no stretch or shrink, +for instance because they only contain plain text. +A~solution would be to increase the page length +by one line if a page turns out to be broken +at a widow line. + +\TeX's output routine can perform this sort of +trick: if the \cs{widowpenalty} is set to +some recognizable value, the output routine +can see by the \cs{outputpenalty} if a widow +line occurred. In that case, the output routine +can temporarily increase the \cs{vsize}, and +let the page builder have another go at +finding a break point. + +Here is the skeleton of such an output routine. +No headers or footers are provided for. +\begin{verbatim} +\newif\ifLargePage \widowpenalty=147 +\newdimen\oldvsize \oldvsize=\vsize +\output={ + \ifLargePage \shipout\box255 + \global\LargePagefalse + \global\vsize=\oldvsize + \else \ifnum \outputpenalty=\widowpenalty + \global\LargePagetrue + \global\advance\vsize\baselineskip + \unvbox255 \penalty\outputpenalty + \else \shipout\box255 + \fi \fi} +\end{verbatim} +The test \cs{ifLargePage} is set to true by the +output routine if the \cs{outputpenalty} +equals the \cs{widowpenalty}. The page box +is then \cs{unvbox}$\,$ed, so that the page builder +will tackle the same material once more. + +%\spoint Example: no indentation top of page +\subsection{Example: no indentation top of page} + +Some output routines can be classified +\howto Prevent indentation on top of page\par +as abuse of the output routine mechanism. +The output routine in this section is a good example of this. + +It is imaginable that one wishes paragraphs not to indent +if they start at the top of a page. (There are plenty of objections +to this layout, but occasionally it is used.) +This problem can be solved using the output routine to +investigate whether the page is still empty and, if so, +to give a signal that a paragraph should not indent. + +Note that we cannot use the fact here +that the page builder comes into play after +the insertion of \cs{everypar}: even if we could +force the output routine to be activated here, +there is no way for it to remove the indentation box. + +The solution given here lets the \cs{everypar} +terminate the paragraph immediately +with \begin{verbatim} +\par\penalty-\specialpenalty +\end{verbatim} +which activates the output routine. +Seeing whether the pagebox is empty (after removing +the empty line and any \cs{parskip} glue), +the output routine then can set a switch +signalling whether the retry of the paragraph +should indent. + +There are some minor matters in the following +routines, the sense of which is left +for the reader to ponder. +\begin{verbatim} +\mathchardef\specialpenalty=10001 +\newif\ifPreventSwitch +\newbox\testbox +\topskip=10pt + +\everypar{\begingroup \par + \penalty-\specialpenalty + \everypar{\endgroup}\parskip0pt + \ifPreventSwitch \noindent \else \indent \fi + \global\PreventSwitchfalse + } +\output{ + \ifnum\outputpenalty=-\specialpenalty + \setbox\testbox\vbox{\unvbox255 + {\setbox0=\lastbox}\unskip} + \ifdim\ht\testbox=0pt \global\PreventSwitchtrue + \else \topskip=0pt \unvbox\testbox \fi + \else \shipout\box255 \global\advance\pageno1 \fi} +\end{verbatim} + + +%\spoint More examples of output routines +\subsection{More examples of output routines} + +A large number of examples of output routines +can be found in~\cite{Sal1} and~\cite{Sal2}. + +%\subject[insert] Insertions +\endofchapter +\chapter{Insertions}\label{insert} + +Insertions are \TeX's way of handling floating information. +\TeX's page builder calculates what insertions and how many +of them will fit on the page; these insertion items are then +placed in insertion boxes which are to be handled by the +output routine. + + + +\begin{inventory} +\item [\cs{insert}] + Start an insertion item. + +\item [\cs{newinsert}] + Allocate a new insertion class. + +\item [\cs{insertpenalties}] + Total of penalties for split insertions. + Inside the output routine, the number of held-over insertions. + +\item [\cs{floatingpenalty}] + Penalty added when an insertion is split. + +\item [\cs{holdinginserts}] + (\TeX3 only) + If this is positive, insertions are not placed in their boxes + at output time. + +\item [\cs{footins}] + Number of the footnote insertion class in plain \TeX. + +\item [\cs{topins}] + Number of the top insertion class. + +\item [\cs{topinsert}] + Plain \TeX\ macro to start a top insert. + +\item [\cs{pageinsert}] + Plain \TeX\ macro to start an insert that will take + up a whole page. + +\item [\cs{midinsert}] + Plain \TeX\ macro that places its argument if there is space, + and converts it into a top insert otherwise. + +\item [\cs{endinsert}] + Plain \TeX\ macro to wind up an insertion item + that started with \cs{topinsert}, \cs{midinsert}, + or \cs{pageinsert}. + +\end{inventory} + + +%\point Insertion items +\section{Insertion items} + +Insertions contain floating information. +\term insertions\par +Handling insertions is a strange interplay between the +user, \TeX's internal workings, and the output routine. +First the user specifies an insertion, which is +a certain amount of vertical material; +then \TeX's page builder decides what insertions should go +on the current page and puts these insertions in insertion boxes; +finally, the output routine has to do something with these boxes. + +An insertion item looks like +\cstoidx insert\par +\begin{disp}\cs{insert}\gr{8-bit number}\lb\gr{vertical mode material}\rb +\end{disp} where the 8-bit number should not be~255, +because \cs{box255} is used by \TeX\ for passing the page to the output +routine. + +The braces around the vertical mode material in an insertion +item can be implicit; they imply a new level of grouping. +The vertical mode material is processed in internal +vertical mode. + +Values of \cs{splittopskip}, \cs{splitmaxdepth}, +and \cs{floatingpenalty} are relevant for split insertions +(see below); the values that are current just before +the end of the group are used. + +Insertion items can appear in vertical mode, horizontal +mode, and math mode. For the latter two modes they have to +migrate to the surrounding vertical list +(see page~\pageref{migrate}). +After an insertion item is put on the vertical list the +page builder is exercised. + + +%\point Insertion class declaration +\section{Insertion class declaration} + +In the plain format +the number for a new insertion class +is allocated by \csidx{newinsert}: +\begin{verbatim} +\newinsert\myinsert % new insertion class +\end{verbatim} +which uses \cs{chardef} to assign a number to the control +sequence. + +Insertion classes are allocated numbering from 254 downward. +As box~255 is used for output, this allocation scheme leaves +\cs{skip255}, \cs{dimen255}, and \cs{count255} +free for scratch use. + +%\point Insertion parameters +\section{Insertion parameters} + +For each insertion class~$n$ four registers are allocated: +\begin{itemize} +\item \cs{box}$\,n$ When the output routine is active this + box contains the insertion items of class~$n$ that should + be placed on the current page. +\item \cs{dimen}$\,n$ This is the maximum space allotted for + insertions of class~$n$ per page. If this amount would + be exceeded \TeX\ will split insertions. +\item \cs{skip}$\,n$ Glue of this size is added the first + time an insertion item of class~$n$ is added to the + current page. This is useful for such phenomena as a rule + separating the footnotes from the text of the page. +\item \cs{count}$\,n$ Each insertion item is a vertical list, + so it has a certain height. However, the effective height, + the amount of influence it has on the text height of the + page, may differ from this real height. + The value of \cs{count}$\,n$ + is then 1000 times the factor by which the height should + be multiplied to obtain the effective height. + + Consider the following examples: + \begin{itemize}\item Marginal notes do not affect + the text height, so the factor should be~0. \item Footnotes + set in double column mode affect the page by half of their height: + the count value should by~500. \item Conversely, footnotes + set at page width underneath a page in double column mode + affect both columns, so \ldash provided that the double column mode + is implemented by applying \cs{vsplit} to a double-height column \rdash + the count value should be~2000.\end{itemize} +\end{itemize} + +%\point Moving insertion items from the contributions list +\section{Moving insertion items from the contributions list} + +The most complicated issue with insertions is the algorithm +that adds insertion items to the main vertical list, +and calculates breakpoints if necessary. + +\TeX\ never changes the \cs{vsize}, but it diminishes the +\csidx{pagegoal} by the (effective) heights of the insertion +items that will appear before a page break. Thus the output +routine will receive a \cs{box255} that has height \cs{pagegoal}, +not necessarily \cs{vsize}. + +\begin{enumerate} +\item When the first insertion of a certain class $n$ occurs + on the current page \TeX\ has to account for the quantity + \cs{skip}$\,n$. This step is executed only if no earlier + insertion item of this class occurs on the vertical list + \ldash this includes insertions that were split \rdash but \cs{box}$\,n$ + need not be empty at this time. + + If \cs{box}$\,n$ is not empty, its height plus depth is multiplied + by \cs{count}$\,n/1000$ and the result is subtracted + from \cs{pagegoal}. Then the \cs{pagegoal} is diminished + by the natural component of \cs{skip}$\,n$. Any stretch and + shrink of \cs{skip}$\,n$ are incorporated in \cs{pagestretch} + and \cs{pageshrink} respectively. +\item If there is a split insertion of class $n$ on the page + \ldash this case and the previous step in the algorithm are + mutually exclusive \rdash the \csidx{floatingpenalty} is added to + \csidx{insertpenalties}. A~split insertion is an insertion item + for which a breakpoint has been calculated as it will not + fit on the current page in its entirety. Thus the insertion + currently under consideration will certainly not wind up + on the current page. +\item After the preliminary action of the two previous points + \TeX\ will place the actual insertion item on the main vertical + list, at the end of the current contributions. + First it will check whether the item will fit without being split. + + There are two conditions to be checked:\begin{itemize}\item + adding the insertion item (plus all previous insertions of that class) + to \cs{box}$\,n$ should not let + the height plus depth of that box exceed \cs{dimen}$\,n$, and + \item either the effective height of the insertion is negative, or + \cs{pagetotal} plus \cs{pagedepth} minus \cs{pageshrink} + plus the effective size of the insertion should be less than + \cs{pagegoal}.\end{itemize} + If these conditions are satisfied, \cs{pagegoal} is diminished + by the effective size of the insertion item, that is, + by the height plus depth, multiplied by \cs{count}$n/1000$. + +\item Insertions that fail on one of the two conditions in the + previous step of the algorithm will be considered for splitting. + \TeX\ will calculate the size of the maximal portion to + be split off the insertion item, such that + \begin{enumerate}\item adding this portion + together with earlier insertions of this class to \cs{box}$\,n$ + will not let the size of the box exceed \cs{dimen}$\,n$, + and \item the effective size of this portion, + added to \cs{pagetotal} plus \cs{pagedepth}, will not + exceed \cs{pagegoal}. Note that \cs{pageshrink} is not taken + into account this time, as it was in the previous step. + \end{enumerate} + + Once this maximal size to be split off has been determined, + \TeX\ locates the least-cost breakpoint in the current + insertion item that will result in a box with a height + that is equal to this maximal size. The penalty associated + with this breakpoint is added to \cs{insertpenalties}, + and \cs{pagegoal} is diminished by the effective height plus + depth of the box to be split off the insertion item. + +\end{enumerate} + + + +%\point Insertions in the output routine +\section{Insertions in the output routine} + +When the output routine comes into action \ldash more precisely: +when \TeX\ starts processing the tokens in the \cs{output} +token list \rdash all insertions that should be placed on the +current page have been put in their boxes, and +it is the responsibility of the output routine +to put them somewhere in the box that is going to be shipped out. + +\begin{example} The plain \TeX\ output routine +handles top inserts and footnotes by packaging the following +sequence: +\begin{verbatim} +\ifvoid\topins \else \unvbox\topins \fi +\pagebody +\ifvoid\footins \else \unvbox\footins \fi +\end{verbatim} +Unboxing the insertion boxes makes the glue on various parts +of the page stretch or shrink in a uniform manner. +\end{example} + +With \TeX3 the insertion mechanism has been extended slightly: +\cstoidx holdinginserts\par\term \TeX\ version 3\par +the parameter \cs{holdinginserts} can be used to specify that +insertions should not yet be placed in their boxes. +This is very useful if the output routine wants to +recalculate the \cs{vsize}, or if the output routine +is called to do other intermediate calculations instead of +ejecting a page. + +During the output routine the parameter +\csidx{insertpenalties} holds the number of insertion items that +are being held over for the next page. +In the plain \TeX\ output routine this is used after the +last page:\begin{verbatim} +\def\dosupereject{\ifnum\insertpenalties>0 + % something is being held over + \line{}\kern-\topskip\nobreak\vfill\supereject\fi} +\end{verbatim} + +%\point Plain \TeX\ insertions +\section{Plain \TeX\ insertions} + +The plain \TeX\ format has only two insertion classes: +the footnotes and the top inserts. +The macro \csidx{pageinsert} generates +top inserts that are stretched to be exactly \cs{vsize} high. +The \csidx{midinsert} macro tests whether the vertical material +specified by the user fits on the page; if so, it is placed +there; if not, it is converted to a top insert. + +Footnotes are allowed to be split, but once one has been +split no further footnotes should appear on the current +page. This effect is attained by setting +\begin{verbatim} +\floatingpenalty=20000 +\end{verbatim} +The \cs{floatingpenalty} is added to \cs{insertpenalties} +if an insertion follows a split insertion of the same +class. However, \cs{floatingpenalty}${}>10\,000$ has infinite +cost, so \TeX\ will take an earlier breakpoint for +splitting off the page from the vertical list. + +Top inserts essentially contain only a vertical box +which holds whatever the user specified. Thus such an insert +cannot be split. However, the \csidx{endinsert} macro +puts a \cs{penalty100} on top of the box, so the +insertion can be split with an empty part before the split. +The effect is that the whole insertion is carried over to +the next page. As the \cs{floatingpenalty} for top inserts +is zero, arbitrarily many of these inserts can be moved forward +until there is a page with sufficient space. + +Further examples of insertion macros can be found +in~\cite{Sal3}. + +%\message{Maybe spaceleft example?} + +%%%% end of input file [page] + +%\InputFile:io +%%%% this is input file [io] +%\subject[io] File Input and Output +\endofchapter +\chapter{File Input and Output}\label{io} + +This chapter treats the various ways in which \TeX\ can read from +\mdqon +\term I/""O\par +\mdqoff +and write to external files. + +\begin{inventory} +\item [\cs{input}] + Read a specified file as \TeX\ input. + +\item [\cs{endinput}] + Terminate inputting the current file after the current line. + +\item [\cs{pausing}] + Specify that \TeX\ should pause after each line that is + read from a file. + +\item [\cs{inputlineno}] + Number of the current input line. + + +\item [\cs{write}] + Write a \gr{general text} to the terminal or to a file. + +\item [\cs{read}] + Read a line from a stream into a control sequence. + +\item [\cs{newread \cs{newwrite}}] +\mdqon + Macro for allocating a new input/""output stream. +\mdqoff + +\item [\cs{openin \cs{closein}}] + Open/close an input stream. + +\item [\cs{openout \cs{closeout}}] + Open/close an output stream. + +\item [\cs{ifeof}] + Test whether a file has been fully read, or does not exist. + +\item [\cs{immediate}] + Prefix to have output operations executed right away. + +\item [\cs{escapechar}] + Number of the character that is used + when control sequences are being converted + into character tokens. + \IniTeX\ default:~92. + +\item [\cs{newlinechar}] + Number of the character that triggers a new line in + \cs{write} statements. + +\end{inventory} + + +%\point Including files: \cs{input} and \cs{endinput} +\section{Including files: \protect\cs{input} and \protect\cs{endinput}} + +Large documents can be segmented in \TeX\ by putting +\term input files\par\cstoidx input\par +parts in separate files, and loading these with \cs{input} +into the master file. The exact syntax for +file names is implementation dependent; most of the +time a \n{.tex} file extension is assumed if no explicit +extension is given. +File names can be delimited with a space or with \cs{relax}. +The \cs{input} command is expandable. + +If \TeX\ encounters in an input file the +\csidx{endinput} statement, it acts as if the file +ends after the line on which the statement occurs. +Any statements on the same line as \cs{endinput} are +still executed. +The \cs{endinput} statement is expandable. + +%\point File I{/}O +\section{File I{/}O} + +\TeX\ supports input and output streams for reading and writing +\altt +files one line at a time. + +%\spoint Opening and closing streams +\subsection{Opening and closing streams} + +\TeX\ supports up to 16 simultaneous input and 16 output streams. +\term streams\par +The plain \TeX\ macros +\csidx{newread} and \csidx{newwrite} give the number of an unused +stream. This number is assigned by a \cs{chardef} command. +Input streams are completely independent of output +streams. + +Input streams are opened by +\cstoidx openin\par +\begin{disp}\cs{openin}\gr{4-bit number}\gr{equals}\gr{filename}\end{disp} +and closed by +\cstoidx closein\par +\begin{disp}\cs{closein}\gr{4-bit number}\end{disp} + +Output streams are opened by +\cstoidx openout\par +\begin{disp}\cs{openout}\gr{4-bit number}\gr{equals}\gr{filename}\end{disp} +and closed by +\cstoidx closeout\par +\begin{disp}\cs{closeout}\gr{4-bit number}\end{disp} + +If an output file does not yet exist, it is created +by \cs{openout}; if it did exist, an \cs{openout} will +cause it to be overwritten. + +The output operations \cs{openout}, \cs{closeout}, +and \cs{write} can all three be prefixed by \cs{immediate}; +see below. + +%\spoint Input with \cs{read} +\subsection{Input with \cs{read}} + +In addition to the \cs{input} command, which reads a whole +file, \TeX\ has the \csidx{read} operation, which +reads one line from a file (or from the user terminal). +The syntax of the read command is + \begin{disp}\cs{read}\gr{number}\n{to}\gr{control sequence}\end{disp} +The effect of this statement is that one input line +is read from the designated stream, and the control +sequence is defined as a macro without parameters, having +that line as replacement text. + +If the input line is not balanced with respect to braces, +\TeX\ will read more than one line, continuing for as long +as is necessary to get a balanced token list. +\TeX\ implicitly appends an empty line to each input stream, +\alt +so the last \cs{read} operation on a stream will always +yield a single \cs{par} token. + +Read operations from any stream outside the range 0--15 \ldash or +streams not associated with an open file, or on which the file +end has been reached \rdash +read from the terminal. If the stream number is positive +the user is prompted with the name of the control sequence +being defined by the \cs{read} statement. + +\begin{example}\begin{verbatim} +\read16 to \data +\end{verbatim} +displays a prompt \begin{verbatim} +\data= +\end{verbatim} +and typing `my name' +in response makes the read statement equivalent +to \begin{verbatim} +\def\data{my name } +\end{verbatim} +The space at the end of the input derives from the line end; +to prevent this one could write +\begin{verbatim} +{\endlinechar=-1 \global\read16 to \data} +\end{verbatim} +\end{example} + +%\spoint Output with \cs{write} +\subsection{Output with \cs{write}} + +\TeX's \csidx{write} command + \begin{disp}\cs{write}\gr{number}\gr{general text}\end{disp} +writes a balanced token list to a file which has been opened +by \cs{openout}, to the log file, or to the terminal. + +Write operations to a stream outside 0--15 \ldash or to a +stream that is not associated with an open file \rdash go to the log file; +if the stream number is positive they +go to the terminal as well as to the log file. + +The token list argument of \cs{write}, defined as + \begin{disp}\gr{general text} $\longrightarrow$ \gr{filler}% + \lb\gr{balanced text}\gr{right brace}\end{disp} +can have an implicit opening brace. +This argument is expanded as if it were the replacement +text of an \cs{edef}, so, for instance, +any macros and conditionals appearing are expanded. +No commands are executed, however. +This expansion occurs +at the time of shipping out; see below. +Until that time the argument token list is stored +in a whatsit item on the current list. +See further Chapter~\ref{expand} for +a discussion of expansion during writing. + +A control sequence output by \cs{write} (or \cs{message}) +is represented with a trailing space, and using +character number \cs{escapechar} +for the escape character. +The \IniTeX\ default for this is~92, +the code for the backslash. +The trailing space can be prevented by prefixing the control +sequence with \cs{string}. + +%\point Whatsits +\section{Whatsits} + +There is an essential difference +\term whatsits\par +in execution between input and output: +operations concerning output +(\cs{openout}, \cs{closeout}, \cs{write}) +are not executed immediately; instead, they are saved until +the box in which they appear is shipped out +to the \n{dvi} file. + +Writes and the other two output operations are placed +in `whatsit' items on whichever list is currently being built. +The actual operation occurs when the part of the page +that has the item is shipped out to the \n{dvi} file. +This delayed output is made necessary by \TeX's +asynchronous output routine behaviour. +See a worked-out example on page~\pageref{expand:write}. + +An \verb.\immediate\write. \ldash or any other \csidx{immediate} output +operation \rdash is executed on the spot, and +does not place a whatsit item on the current list. + +The argument of a \cs{special} command +(see page~\pageref{special}) is also placed in a whatsit. + +Whatsit items in leader boxes are ignored. + +%\point Assorted remarks +\section{Assorted remarks} + +%\spoint Inspecting input +\subsection{Inspecting input} + +\TeX\ records the current line number in the current input file +in the \gr{internal integer} parameter \csidx{inputlineno} +(in \TeX3). + +If the parameter \csidx{pausing} is positive, \TeX\ shows +every line that is input on the terminal screen, +and gives the user the opportunity +to insert commands. These can for instance be \cs{show} commands. +Inserted commands are treated as if they were directly +in the source file: it is for instance not necessary +to prefix them with~`i', as would be necessary when +\TeX\ pauses for an error. + +%\spoint Testing for existence of files +\subsection{Testing for existence of files} + +\TeX\ is not the friendliest of systems when you +\howto Test whether a file exists\par +ask it to input a non-existing file. Therefore the following +sequence of commands can be used to prevent trouble\label{ex:eof}: +\begin{verbatim} +\newread\instream \openin\instream= fname.tex +\ifeof\instream \message{File 'fname' does not exist!} +\else \closein\instream \input fname.tex +\fi +\end{verbatim} +Here an input stream is opened with the given file name. +The end-of-file test is also true +if an input stream does not correspond to a physical file, +so if this conditional is not true, +the file exists and an \cs{input} command can safely be given. + +%\spoint Timing problems +\subsection{Timing problems} + +The synchronization between write operations on the +one hand, and opening/closing operations +of files on the other hand, +can be a crucial point. Auxiliary files, such as are +used by various formats to implement cross-references, +are a good illustration of this. + +Suppose that during a run of \TeX\ the auxiliary file is written, and +\howto Input a file that was created in the same run of \TeX\par +at the end of the run it has to be input again for a variety +of purposes (such as seeing whether references have changed). +An \cs{input} command is executed right away, so +the file must have been closed with an \verb=\immediate\closeout=. +However, now it becomes possible that the file is closed +before all writes to it have been performed. +The following sequence remedies this: +\begin{verbatim} +\par\vfil\penalty -10000 \immediate\closeout\auxfile +\end{verbatim} +The first three commands activate the output routine +in order to close off the last page, +so all writes will indeed have been performed before the +file is closed. + +%\spoint \cs{message} versus \cs{immediate}\cs{write}16 +\subsection{\cs{message} versus \cs{immediate}\cs{write}16} + +Messages to the user can be given using +\csidx{message}\gr{general text}, which writes to the terminal. +Messages are appended to one another; +the line is wrapped when the line +length (a~\TeX\ compile-time constant) has been reached. +In \TeX\ version2, +a~maximum of 1000 characters is written per message; +this is not a compile-time constant, but is hard-wired +into the \TeX\ program. + +Each message given with \verb=\immediate\write= +starts on a new line; the user can force a new line +in the message by including the character with +number~\csidx{newlinechar}. This parameter also works +in \cs{message}. + +%\spoint Write inside a vertical box +\subsection{Write inside a vertical box} + +Since a write operation winds up on the vertical list in a whatsit, +issuing one at the start of a \cs{vtop} +will probably influence the height of that box +(see Chapter~\ref{boxes}). As an example, +\begin{verbatim} +have the \vtop{\write\terminal{Hello!}\hbox{more text}} +dangling from +\end{verbatim} +will have the~\vtop{\write-1{vtop gezien}\hbox{more text}}~dangling +from the baseline (and when this book is \TeX ed the +message `Hello!' appears on the screen). + +%\spoint Expansion and spaces in \cs{write} and \cs{message} +\subsection{Expansion and spaces in \cs{write} and \cs{message}} + +Both \cs{write} and \cs{message} expand their argument +as if it were the replacement text of an \cs{edef}. +Therefore \begin{verbatim} +\def\a{b}\message{\a} +\end{verbatim} +will +write out~`\n b'. + +Unexpandable control sequences are displayed with a trailing +space (and prefixed with the \cs{escapechar}): +\begin{verbatim} +\message{\hbox\vbox!} +\end{verbatim} +will write out +`\verb>\hbox \vbox !>'. Undefined control sequences give an error here. + +Expandable control sequences can be written out with some +care:\begin{verbatim} +\message{\noexpand\ifx} +\message{\string\ifx} +{\let\ifx\relax \message{\ifx}} +\end{verbatim} +all write out `\verb>\ifx>'. + +Note, however, that spaces after expandable control sequences +are removed in the input processor, which goes into state~$S$ +after a control sequence. Therefore +\begin{verbatim} +\def\a{b}\def\c{d} +\message{\a \c} +\end{verbatim} +writes out `\n{bd}'. +Inserting a space can be done as follows: +\begin{verbatim} +\def\space{ } % in plain TeX +\message{\a\space\c} +\end{verbatim} +displays `\n{b d}'. +Note that\begin{verbatim} + +\message{\a{ }\c} +\end{verbatim} +does not work: it displays `\verb=b{ }d=' +since braces are unexpandable character tokens. + +%%%% end of input file [io] + +%\InputFile:alloc +%%%% this is input file [alloc] +%\subject[alloc] Allocation +\endofchapter +\chapter{Allocation}\label{alloc} + +\TeX\ has registers of a number of types. For some of these, +explicit commands exist to define a synonym for a certain register; +for all of them macros exist in the plain format +to allocate an unused register. This chapter treats +the synonym and allocation commands, and discusses +some guidelines for macro writers regarding allocation. + +\begin{inventory} +\item [\cs{countdef}] + Define a synonym for a \cs{count} register. +\item [\cs{dimendef}] + Define a synonym for a \cs{dimen} register. +\item [\cs{muskipdef}] + Define a synonym for a \cs{muskip} register. +\item [\cs{skipdef}] + Define a synonym for a \cs{skip} register. +\item [\cs{toksdef}] + Define a synonym for a \cs{toks} register. +\item [\cs{newbox}] + Allocate an unused \cs{box} register. +\item [\cs{newcount}] + Allocate an unused \cs{count} register. +\item [\cs{newdimen}] + Allocate an unused \cs{dimen} register. +\item [\cs{newfam}] + Allocate an unused math family. +\item [\cs{newinsert}] + Allocate an unused insertion class. +\item [\cs{newlanguage}] + (\TeX3 only) + Allocate a new language number. +\item [\cs{newmuskip}] + Allocate an unused \cs{muskip} register. +\item [\cs{newskip}] + Allocate an unused \cs{skip} register. +\item [\cs{newtoks}] + Allocate an unused \cs{toks} register. +\item [\cs{newread}] + Allocate an unused input stream. +\item [\cs{newwrite}] + Allocate an unused output stream. +\end{inventory} + +%\point Allocation commands +\section{Allocation commands} + +In plain \TeX, \cs{new...} macros are defined for +allocation of registers. +The registers of \TeX\ fall into two classes that are +\term registers, allocation of\par +allocated in different ways. This is treated below. + +The \csidx{newlanguage} macro of plain \TeX\ +does not allocate any register. Instead it merely assigns +a number, starting from~0. +\TeX\ (version~3) can have at most 256 different +sets of hyphenation patterns. + +The \cs{new...} macros of plain \TeX\ are defined to be +\cs{outer} (see Chapter~\ref{macro} for a precise explanation), +which precludes use of the allocation macros in other macros. +Therefore the \LaTeX\ format redefines these macros +without the \cs{outer} prefix. + +%\spoint \cs{count}, \cs{dimen}, \cs{skip}, \cs{muskip}, \cs{toks} +\subsection{\cs{count}, \cs{dimen}, \cs{skip}, \cs{muskip}, \cs{toks}} + +For these registers there exists a \gr{registerdef} command, +for instance \cs{countdef}, to couple a specific register +to a control sequence: +\begin{Disp}\gr{registerdef}\gr{control + sequence}\gr{equals}\gr{8-bit number}\end{Disp} + +After the definition \begin{verbatim} +\countdef\MyCount=42 +\end{verbatim} +the allocated register can be used as +\begin{verbatim} +\MyCount=314 +\end{verbatim} +or \begin{verbatim} +\vskip\MyCount\baselineskip +\end{verbatim} + +The \gr{registerdef} commands are used in plain \TeX\ macros +\cs{newcount} et cetera that allocate an unused register; +after\begin{verbatim} +\newcount\MyCount +\end{verbatim} +\cs{MyCount} can be used +exactly as in the above two examples. + +%\spoint \cs{box}, \cs{fam}, \cs{write}, \cs{read}, \cs{insert} +\subsection{\cs{box}, \cs{fam}, \cs{write}, \cs{read}, \cs{insert}} + +For these registers there exists no \gr{registerdef} command in \TeX, +so \cs{chardef} is used to allocate box registers +in the corresponding plain \TeX\ macros \cs{newbox}, for instance. + +The fact that \cs{chardef} is used implies that the +defined control sequence does not stand for the register itself, +but only for its number. Thus after \begin{verbatim} +\newbox\MyBox +\end{verbatim} +it is necessary to write \begin{verbatim} +\box\MyBox +\end{verbatim} +Leaving out the \cs{box} means that the character +in the current font with number +\cs{MyBox} is typeset. The \cs{chardef} command +is treated further in Chapter~\ref{char}. + +%\point Ground rules for macro writers +\section{Ground rules for macro writers} + +The \cs{new...} macros of plain \TeX\ have been designed +to form a foundation for macro packages, such that +several of such packages can operate without collisions +in the same run of \TeX. In appendix~B of \TeXbook\ +Knuth formulates some ground rules that macro writers should +adhere to. +\begin{enumerate} +\item The \cs{new...} macros do not allocate registers +with numbers~0--9. These can therefore be used as `scratch' +registers. However, as any macro family can use them, +no assumption can be made about the permanency of their +contents. Results that are to be passed from one call to +another should reside in specifically allocated registers. + +Note that count registers 0--9 are used for page identification +in the \n{dvi} file (see Chapter~\ref{TeXcomm}), so no global assignments +to these should be made. + +\item \cs{count255}, \cs{dimen255}, and \cs{skip255} are +also available. This is because inserts are +allocated from 254 downward and, together with an insertion box, +a count, dimen, and skip register, +all with the same number, are allocated. +Since \cs{box255} is used by the output routine +(see Chapter~\ref{output}), +the count, dimen, and skip with number~255 are freely available. + +\item Assignments to scratch registers~0, 2, 4, 6, 8, and~255 +should be local; assignments to registers~1, 3, 5, 7,~9 +should be \cs{global} (with the exception of the \cs{count} +registers). This guideline prevents `save +stack build-up' (see Chapter~\ref{error}). + +\item Any register can be used inside a group, as \TeX's +grouping mechanism will restore its value outside +the group. There are two conditions on this use of +a register: +no global assignments should be made to it, and +it must not be possible that other macros may be +activated in that group that perform global assignments +to that register. + +\item Registers that are used over longer periods of time, +or that have to survive in between calls of different +macros, should be allocated by \cs{new...}. +\end{enumerate} + + +%%%% end of input file [alloc] + +%\InputFile:run +%%%% this is input file [run] +%\subject[run] Running \TeX +\endofchapter +\chapter{Running \TeX}\label{run} + +This chapter treats the run modes of \TeX, and some +other commands associated with the job being processed. + +\begin{inventory} +\item [\cs{everyjob}] + Token list that is inserted at the start of each new job. + +\item [\cs{jobname}] + Name of the main \TeX\ file being processed. + +\item [\cs{end}] + Command to finish off a run of \TeX. + +\item [\cs{bye}] + Plain \TeX\ macro to force the final output. + +\item [\cs{pausing}] + Specify that \TeX\ should pause after each line that is + read from a file. + +\item [\cs{errorstopmode}] + \TeX\ will ask for user input on the occurrence of an error. + +\item [\cs{scrollmode}] + \TeX\ fixes errors itself, + but will ask the user for missing files. + +\item [\cs{nonstopmode}] + \TeX\ fixes errors itself, + and performs an emergency stop on serious errors + such as missing input files. + +\item [\cs{batchmode}] + \TeX\ fixes errors itself + and performs an emergency stop on serious errors + such as missing input files, + but no terminal output is generated. + +\end{inventory} + +%\point Jobs +\section{Jobs} + +\TeX\ associates with each run a name for the file +\term job\par +being processed: the \csidx{jobname}. If \TeX\ is run +interactively +\ldash meaning that it has been invoked without a file argument, +and the user types commands \rdash +the jobname is \n{texput}. + +The \cs{jobname} can be used to generate +the names of auxiliary files to be read or +written during the run. For instance, for a file \n{story.tex} +the \cs{jobname} is \n{story}, and writing +\begin{verbatim} +\openout\Auxiliary=\jobname.aux +\openout\TableOfContents=\jobname.toc +\end{verbatim} +will create the files \n{story.aux} and \n{story.toc}. + +%\spoint Start of the job +\subsection{Start of the job} + +\TeX\ starts each job by inserting the \csidx{everyjob} token +list into the command stream. +Setting this variable during a run of \TeX\ has no use, +but a format can use it to identify itself to the user. +If a +format fills the token list, the commands therein are automatically +executed when \TeX\ is run using that format. + +%\spoint End of the job +\subsection{End of the job} + +A \TeX\ job is terminated by the \csidx{end} command. This +may involve first forcing the output routine to process any +remaining material (see Chapter~\ref{page:break}). +If the end of job occurs inside a group +\TeX\ will give a diagnostic +message. The \cs{end} command is not allowed in internal +vertical mode, because this would be inside a vertical box. + +Usually some sugar coating of the \cs{end} command is necessary. +For instance the plain \TeX\ macro \csidx{bye} is defined +as \begin{verbatim} +\def\bye{\par\vfill\supereject\end} +\end{verbatim} +where the \cs{supereject} takes care of any leftover insertions. + +%\spoint The log file +\subsection{The log file} + +For each run \TeX\ creates a log file. Usually this will be +\term log file\par +a file with as name the value of \cs{jobname}, and the +extension \n{.log}. Other extensions such as \n{.lis} +are used by some implementations. +This log file contains all information that +is displayed on the screen during the run of \TeX, but +it will display some information more elaborately, and it +can contain statistics that are usually not displayed on +the screen. If the parameter \cs{tracingonline} +has a positive value, all the log file information will be +shown on the screen. + +Overfull and underfull boxes are reported on the terminal +screen, and they are dumped using the parameters +\cs{showboxdepth} and \cs{showboxbreadth} in the log file +(see Chapter~\ref{trace}). These parameters are also used +for box dumps caused by the \cs{showbox} command, and +for the dump of boxes written by \cs{shipout} +if \cs{tracingoutput} is set to a positive value. + +Statistics generated by commands such as \cs{tracingparagraphs} +will be written to the log file; if \cs{tracingonline} is positive +they will also be shown on the screen. + +Output operations to a stream that is not open, or to a +stream with a number that is not in the range 0--15, +go to the log file. If the stream number is positive, +they also go to the terminal. + +%\point Run modes +\section{Run modes} + +By default, \TeX\ goes into \cs{errorstopmode} if an error occurs: +\term run modes\par\cstoidx errorstopmode\par +it stops and asks for input from the user. Some implementations + have a way of forcing \TeX\ into errorstopmode +when the user interrupts \TeX, so that +the internal state of \TeX\ can be inspected (and altered). +See page~\pageref{interaction} for ways to switch the run +mode when \TeX\ has been interrupted. + +Often, \TeX\ can +fix an error itself if the user asks \TeX\ just to continue +(usually by hitting the return key), +but sometimes (for instance in alignments) +it may take a while before \TeX\ is on the +right track again (and sometimes it never is). +In such cases the user may want to +turn on \csidx{scrollmode}, +which instructs \TeX\ to fix as best it can any +occurring error without confirmation from the user. +This is usually done by typing `s' when \TeX\ asks +for input. + +In \cs{scrollmode}, \TeX\ also does not ask for input +after \cs{show...} commands. +\alt +However, some errors, such as a file that could not be +found for \cs{input}, are not so easily remedied, so +the user will still be asked for input. + +With \csidx{nonstopmode} \TeX\ will scroll through errors and, +in the case of the kind of error that cannot be recovered from, +it will make an emergency stop, aborting the run. +Also \TeX\ will abort the run if a \cs{read} is attempted +from the terminal. +The \csidx{batchmode} differs only from nonstopmode in that +it gives messages only to the log file, not to the terminal. + +\endofchapter +\chapter{\TeX\ and the Outside World}\label{TeXcomm} + +This +chapter treats those commands that bear relevance to +\n{dvi} files and formats. It gives some global information +about \IniTeX, font and format files, +Computer Modern typefaces, and \web. + +\begin{inventory} +\item [\cs{dump}] + Dump a format file; possible only in \IniTeX, + not allowed inside a group. + +\item [\cs{special}] + Write a \gr{balanced text} to the \n{dvi} file. + +\item [\cs{mag}] + 1000 times the magnification of the document. + +\item [\cs{year}] + The year of the current job. + +\item [\cs{month}] + The month of the current job. + +\item [\cs{day}] + The day of the current job. + +\item [\cs{time}] + Number of minutes after midnight that the current job started. + +\item [\cs{fmtname}] + Macro containing the name of the format dumped. + +\item [\cs{fmtversion}] + Macro containing the version of the format dumped. + +\end{inventory} + + +%\point \TeX, \IniTeX, \VirTeX +\section{\TeX, \IniTeX, \VirTeX} + +In the terminology established in {\italic \TeX: the Program}, +\cite{Knuth:TeXprogram}, +\term\TeX\par\term\IniTeX\par\term\VirTeX\par +\TeX\ programs come in three flavours. +\IniTeX\ is a version of \TeX\ that can generate formats; +\VirTeX\ is a production version without preloaded format, +and \TeX\ is a production version with +preloaded (plain) format. Unfortunately, this terminology is +not adhered to in general. A~lot of systems do not use preloaded +formats (the procedure for making them may be impossible on +some operating systems), +and call the `virgin \TeX' simply \TeX. +This manual also follows that convention. + +%\spoint Formats: loading +\subsection{Formats: loading} + +A format file (usually with extension~\n{.fmt}) +is a compact dump of \TeX's internal structures. +\term format files\par +Loading a format file takes a considerably shorter time than +would be needed for +loading the font information and the macros that +constitute the format. + +Both \TeX\ and \IniTeX\ can load a format; the user specifies +this by putting the name on the command line +\begin{verbatim} +% tex &plain +\end{verbatim} +or at the \n{**} prompt +\begin{verbatim} +% tex +This is TeX. Version .... +** &plain +\end{verbatim} +preceded by an ampersand (for UNIX, this should be \verb>\&> on +the command line). An input file name can follow the +format name in both places. + +\IniTeX\ does not need a format, +but if no format is specified for (Vir)\TeX, it will try to +load the plain format, and halt if that cannot be found. + +%\spoint Formats: dumping +\subsection{Formats: dumping} + +\IniTeX\ is the only version of \TeX\ +that can dump a format, since it is +the only version of \TeX\ that has +the command~\csidx{dump}, +which causes the internal structures +to be dumped as a format. +It is also the only version of \TeX\ that has the command +\cs{patterns}, which +is needed to specify a list of hyphenation +patterns. + +Dumping is not allowed inside a group, that is +\begin{verbatim} +{ ... \dump } +\end{verbatim} +is not allowed. This restriction +prevents difficulties with \TeX's save stack. +After the \cs{dump} command \TeX\ gives an elaborate listing of +its internal state, and of the font names associated with +fonts that have been loaded and ends the job. + +An interesting possibility arises from the fact that +\IniTeX\ can both load and dump a format. +Suppose you have written a set of macros that build +on top of plain \TeX, \n{superplain.tex}. +You could then call +\begin{verbatim} +% initex &plain superplain +*\dump +\end{verbatim} +and get a format file \n{superplain.fmt} that +has all of plain, and all of your macros. + +%\spoint Formats: preloading +\subsection{Formats: preloading} + +On some systems it is possible to interrupt a running program, +and save its `core image' such that this can be started as +an independent program. +The executable made from the +core image of a \TeX\ program interrupted after it has loaded +a format is called a \TeX\ program with preloaded format. +The idea behind preloaded formats is +that interrupting \TeX\ after it has loaded a format, and making +this program available to the user, +saves in each run the time for loading the format. +In the good old days when computers were quite a bit slower +this procedure made sense. +Nowadays, it does not seem so necessary. +Besides, dumping a core image may not always be possible. + +%\spoint The knowledge of \IniTeX +\subsection{The knowledge of \IniTeX} + +If no format has been loaded, \IniTeX\ knows very little. +For instance, it has no open/close group characters. +However, it can not be completely devoid of knowledge +lest there be no way to define anything. + +Here is the extent of its knowledge. +\begin{itemize} \mathsurround=1.5pt +%\flushright:no +\item \verb>\catcode`\\=0>, \verb>\escapechar=`\\> + (see page~\pageref{ini:esc}). +\item \verb>\catcode`\^^M=5>, \verb>\endlinechar=`\^^M> + (see page~\pageref{ini:eol}). +\item \verb>\catcode`\ =10> + (see page~\pageref{ini:sp}). +\item \verb>\catcode`\%=14> + (see page~\pageref{ini:comm}). +\item \verb>\catcode`\^^?=15> + (see page~\pageref{ini:invalid}). +\item \cs{catcode}$x$\n{=11} for $x={}$\n{`a..`z,`A..`Z} + (see page~\pageref{ini:let}). +\item \cs{catcode}$x$\n{=12} for all other character codes\nl + (see page~\pageref{ini:other}). +\item \cs{sfcode}$x$=\n{999} for $x={}$\n{`A..`Z}, + \cs{sfcode}$x$\n{=1000} for all other characters + (see page~\pageref{ini:sf}). +\item \verb>\lccode`a..`z,`A..`Z=`a..`z>, \verb>\uccode`a..`z,`A..`Z=`A..`Z>, + \cs{lccode}$x$\n{=0}, \cs{uccode}$x$\n{=0} for all other characters + (see page~\pageref{ini:uclc}). +\item \verb>\delcode`.=0>, \cs{delcode}$x$\n{=-1} for all other characters + (see page~\pageref{ini:del}). +\item \cs{mathcode}$x$\n{="!7100}${}+x$ for all lowercase and uppercase + letters, \cs{mathcode}$x$\n{="!7000}${}+x$ for all digits, + \cs{mathcode}$x$\n=$x$ for all other characters + (see page~\pageref{ini:fam}). +\item \cs{tolerance=10000}, \cs{mag=1000}, + \cs{maxdeadcycles=25}. +\end{itemize} + +%\spoint Memory sizes of \TeX\ and \IniTeX +\subsection{Memory sizes of \TeX\ and \IniTeX} + +The main memory size of \TeX\ and \IniTeX\ is controlled by +four constants in the source code: +\n{mem\_bot}, \n{mem\_top}, \n{mem\_min}, and~\n{mem\_max}. +For Ini\TeX's memory \n{mem\_bot${}={}$mem\_min} +and \n{mem\_top${}={}$mem\_max}; +for \TeX\ \n{mem\_bot} and \n{mem\_top} record the main memory +size of the Ini\TeX\ used to dump the format. +Thus versions of \TeX\ and \IniTeX\ have to be adapted +to each other in this respect. + +\TeX's own main memory can be bigger than that of the +corresponding \IniTeX: in general +\n{mem\_min${}\leq{}$mem\_bot} and \n{mem\_top${}\leq{}$mem\_max}. + +For \IniTeX\ a smaller main memory can suffice, +as this program is typically +not meant to do real typesetting. +There may even be a real need for the main memory +to be smaller, because \IniTeX\ needs a lot of auxiliary +storage for initialization and for building the +hyphenation table. + + +%\point More about formats +\section{More about formats} + +%\spoint Compatibility +\subsection{Compatibility} + +\TeX\ has a curious error message: `Fatal format error: I'm stymied', +which is given if \TeX\ tries to load a format that was made +with an incompatible version of \IniTeX. See the point +above about memory sizes, and Chapter~\ref{error} for +the hash size (parameters \n{hash\_size} and \n{hash\_prime}) +and the hyphenation exception dictionary (parameter \n{hyph\_size}). + +%\spoint Preloaded fonts +\subsection{Preloaded fonts} + +During a run of \TeX\ the only information needed about fonts +is the data that is found in the \n{tfm} files (see below). +Since a run of \TeX, especially if the input contains math material, +can easily access 30--40 fonts, the disk access for +all the \n{tfm} files can become significant. +Therefore the plain format and \LaTeX\ load these +metrics files in \IniTeX. A~\TeX\ version using such a format +does not need to load any \n{tfm} files. + +On the other hand, if a format has the possibility of accessing +a range of typefaces, it may be advantageous to have metrics +files loaded on demand during the actual run of \TeX. + +%\spoint The plain format +\subsection{The plain format} + +The first format written for \TeX, and the basis for all +later ones, +is the plain format, described in \TeXbook. +It is a mixture of \begin{itemize} +\item definitions and macros one simply cannot live without +such as the initial \cs{catcode} assignments, +all of the math delimiter definitions, +and the \cs{new...} macros; +\item constructs that are useful, but for which \LaTeX\ +and other packages use +a different implementation, such as the tabbing environment; and +\item some macros that are insufficient for any but the +simplest applications: \cs{item} and \cs{beginsection} +are in this category.\end{itemize} + +It is the first category which Knuth meant to serve as a +foundation for future macro packages, so that they +can live peacefully together (see Chapter~\ref{alloc}). +This idea is reflected in the fact that the name `plain' +is not capitalized: it is the basic set of macros. + +%\spoint The \LaTeX\ format +\subsection{The \LaTeX\ format} + +The \LaTeX\ format\term\LaTeX\par, +written by Leslie Lamport of Digital Equipment Corporation +and described in~\cite{Lamport:LaTeX}, +was released around 1985. +The \LaTeX\ format, using its own version +of \n{plain.tex} (called \n{lplain.tex}), +is not compatible with plain \TeX; +a~number of plain macros are not available. Still, it contains +large parts of the plain format (even when they overlap with +its own constructs). + +\LaTeX\ is a powerful format with facilities such as +marginal notes, floating objects, cross referencing, +and automatic table of contents generation. +Its main drawback is that the `style files' which +define the actual layout are quite hard to write +(although \LaTeX\ is in the process of a major revision, +in which this problem will be tackled; +see \cite{Frank} and~\cite{Frank2}). +As a result, +people have had at their disposal mostly the styles +written by Leslie Lamport, the layout of which is +rather idiosyncratic. See~\cite{BEP} for a successful +attempt to replace these styles. + +%\spoint Mathematical formats +\subsection{Mathematical formats} + +There are two formats with extensive facilities for +mathematics typesetting: +\AmsTeX~\cite{Ams} +(which originated at the American Mathematical Society) +and \LamsTeX~\cite{Lams}. +The first of these includes more facilities than plain \TeX\ +or \LaTeX\ for typesetting mathematics, but it lacks +features such as automatic numbering and cross-referencing, +available in \LaTeX, for instance. \LamsTeX, then, is the +synthesis of \AmsTeX\ and \LaTeX. Also it includes +still more features for mathematics, such as complicated +tables and commutative diagrams. + +%\spoint Other formats +\subsection{Other formats} + +Other formats than the above exist: +for instance, \n{Phyzzx}~\cite{Phyzzx}, \n{TeXsis}~\cite{TeXsis}, +Macro \TeX~\cite{Amy}, \n{eplain}~\cite{Berry}, +and \n{\TeX T1}~\cite{TeXT1}. +Typically, such formats provide the facilities of \LaTeX, but +try to be more easily adaptable by the user. +Also, in general they +have been written with the intention of being an +add-on product to the plain format. + +This book is also written in an `other format': +the \n{lollipop} format. +\term Lollipop\par +This format does not contain user macros, but the +tools with which a style designer can program them; see~\cite{EL}. + +%\point The \n{dvi} file +\section{The \n{dvi} file} + +The \n{dvi} file (this term stands for `device independent') +\term \n{dvi} file\par +contains the output of a \TeX\ run: it +contains compactly dumped representations of boxes that +have been sent there by \cs{shipout}\gr{box}. The act +of shipping out usually occurs inside the output routine, +but this is not necessarily so. + +%\spoint The \n{dvi} file format +\subsection{The \n{dvi} file format} + +A \n{dvi} file is a byte-oriented file, +consisting of a preamble, a postamble, +and a list of pages. + +Access for subsequent software to a completed \n{dvi} file +is strictly sequential in nature: +the pages are stored as a backwards linked list. This +means that only two ways of accessing are possible: +\begin{itemize} \item given the start of a page, the next can be +found by reading until an end-of-page code is encountered, and +\item starting at the end of the file pages can be read +backwards at higher speed, as each beginning-of-page code +contains the byte position of the previous one.\end{itemize} + +The preamble and postamble contain +\begin{itemize}\item the magnification of the document (see below), +\item the unit of measurement used for the document, and +\item possibly a comment string.\end{itemize} +The postamble contains in addition a list of the font definitions +that appear on the pages of the file. + +Neither the preamble nor the postamble +of the file contains a +table of byte positions of pages. +The full definition of the \n{dvi} file format can be found +in~\cite{Knuth:TeXprogram}. + +%\spoint Page identification +\subsection{Page identification} + +Whenever a \cs{shipout} occurs, \TeX\ also writes the +values of counters 0--9 to the \n{dvi} file and the terminal. +Ordinarily, only counter~0, the page number, is used, and the +other counters are zero. Those zeros are not output to the +terminal. The other counters can be used to indicate further +structure in the document. Log output shows the non-zero +counters and the zero counters in between. + + +%\spoint Magnification +\subsection{Magnification } + +Magnification of a document can be indicated by the \gr{integer +parameter} +\term magnification\par\cstoidx mag\par +\cs{mag}, which specifies 1000 times the magnification +ratio. + +The \n{dvi} file contains the value of \cs{mag} for the +document in its preamble and postamble. +If no {\tt true} dimensions are used +the \n{dvi} file will look the same as when no magnification +would have been used, except for the \cs{mag} value in the +preamble and the postamble. + +Whenever a {\tt true} dimension is used it is divided +by the value of \cs{mag}, so that the final output will have +the dimension as prescribed by the user. +The \cs{mag} parameter cannot be changed after a +\n{true} dimension has been used, or after the first +page has been shipped to the \n{dvi} file. + +Plain \TeX\ has the \csidx{magnification} macro for +globally sizing the document, without changing + the physical size of the page: +\begin{verbatim} +\def\magnification{\afterassignment\m@g\count@} +\def\m@g{\mag\count@ + \hsize6.5truein\vsize8.9truein\dimen\footins8truein} +\end{verbatim} +The explanation for this is +as follows: the command \cs{m@g} is saved with an \cs{afterassignment} +command, and the magnification value (which is 1000 times the +actual magnification factor) is assigned to \cs{count@}. +After this assignment, the macro \cs{m@g} assigns +the magnification value to \cs{mag}, and the horizontal +and vertical size are reset to +their original values {\tt 6.5truein} and {\tt 8.9truein}. +The \cs{footins} is also reset. + +%\point[special] Specials +\section{Specials} +\label{special} + +\mdqon +\TeX\ is to a large degree machine"-independent, but it still needs +\mdqoff +\term specials\par +a hook for machine-dependent extensions. This is the +\csidx{special} command, which writes a \gr{balanced text} +to the \n{dvi} file. \TeX\ does not interpret this token list: +it assumes that the printer driver knows what to do with it. +\cs{special} commands are supposed not to change the +$x$ and $y$ position on the page, so that the implementation +of \TeX\ remains independent of the actual device driver +\term device drivers\par +that handles the \cs{special}. + +The most popular application of specials is probably the +inclusion of graphic material, written in some +page description language, such as PostScript\term PostScript\par. +The size of the graphics can usually be determined from +the file containing it (in the case of encapsulated +PostScript through +the `bounding box' data), so \TeX\ can leave space for +such material. + +%\point Time +\section{Time} + +\TeX\ has four parameters, \csidx{year}, \csidx{month}, \csidx{day}, and +\csidx{time}, that tell +\term time\par\term date\par +the time when the current job started. +After this, the parameters are not updated. +The user can change them at any time. + +All four parameters are integers; the \cs{time} parameter +gives the number of minutes since midnight that the current +job started. + +%\point Fonts +\section{Fonts} + +Font information is split in the \TeX\ system into +the metric information (how high, wide, and deep is a character), +and the actual description of the characters in a font. +\TeX, the formatter, needs only the metric information; +printer drivers and screen previewers need the character +descriptions. With this approach it is for instance possible +for \TeX\ to use with relative ease the resident fonts of +a printer. + +%\spoint Font metrics +\subsection{Font metrics} + +The metric information of \TeX's fonts is stored in \n{tfm} +\term font metrics\par +files, which stands for `\TeX\ font metric' files. +Metrics files contain the following information +(see \cite{Knuth:TeXprogram} for the full definition): +\begin{itemize}\item the design size of a font; +\item the values for the \cs{fontdimen} parameters +(see Chapter~\ref{font}); +\item the height, depth, width, and italic correction + of individual characters; +\item kerning tables; +\item ligature tables; +\item information regarding successors and extensions +of math characters (see Chapter~\ref{mathchar}). +\end{itemize} +Metrics files use a packed format, but they can be converted +to and from a readable format by the auxiliary programs +\n{tftopl} and \n{pltotf} (see~\cite{K:Fuchs}). +Here \n{pl} stands for `property list', +a term deriving from the programming language Lisp. +Files in \n{pl} format are just text, so they can easily be edited; +after conversion +they can then again be used as \n{tfm} files. + +%\spoint[virtual:fonts] Virtual fonts +\subsection{Virtual fonts} +\label{virtual:fonts} + +With `virtual fonts' (see~\cite{K:virt}) it is possible that +\term virtual fonts\par +what looks like one font to \TeX\ resides in more than +one physical font file. Also, virtual fonts can be used +to change in effect the internal organization of font files. + +For \TeX\ itself, the +presence of virtual fonts makes no difference: everything +is still based on \n{tfm} files containing metric +information. However, the screen or printer driver that displays +the resulting \n{dvi} file on the screen or on a printer +will search for files with extension \n{.vf} to determine +how characters are to be interpreted. +The \n{vf} file can, for instance, instruct the driver +to interpret a character as a certain position +in a certain font file, to interpret a character as more +than one position (a~way of forming accented characters), +or to include \cs{special} information (for +instance to set gray levels). + +Readable variants of \n{vf} files have extension \n{vpl}, +analogous to the \n{pl} files for the \n{tfm} files; see above. +Conversion between \n{vf} and \n{vpl} files can be +performed with the \n{vftovp} and \n{vptovf} programs. + +However, because virtual fonts are a matter for +\term device drivers\par +device drivers, no more details will be given in this book. + +%\spoint Font files +\subsection{Font files} + +Character descriptions are stored in three types of files. +\term font files\par +\begin{description} \item [gf] + Generic Font files. +This is the file type that the Metafont program generates. +There are not many previewers or printer drivers that use +this type of file directly. +\item [pxl] + Pixel files. The \n{pxl} format is a pure bitmap format. +Thus it is easy to generate \n{pxl} files from, for instance, +scanner images. + +This format should be superseded by the \n{pk} format. +Pixel files can become rather big, +as their size grows quadratically in the size of the characters. + +\item [pk] + Packed files. Pixel files can be packed by a form of run-length +encoding: instead of storing the complete bitmap only the +starting positions and lengths of `runs' of black and white +pixels are stored. This makes the size of \n{pk} files +approximately linear in the size of the characters. +However, a previewer or printer driver using a packed font file +has to unpack it before it is able to use it. +\end{description} + +The following conversion programs exist: +\n{gftopxl}, \n{gftopk}, \n{pktopxl}, \n{pxltopk}. + +%\spoint Computer Modern +\subsection{Computer Modern} + +The only family of typefaces that comes with \TeX\ +in the standard distribution is the `Computer +\term Computer Modern typefaces\par +Modern' family. This is an adaptation (using the terminology +of~\cite{S}) by Donald Knuth of the Monotype Modern~8A typeface +that was used for the first volume of his {\italic Art of Computer +Programming\/} series. The `modern faces' all derive from the +types that were cut between 1780 and 1800 by Firmin Didot in +France, Giambattista Bodoni in Italy, and Justus Erich Walbaum +in Germany. After the first two, these types are also called +`Didone' types. This name was coined in the Vox classification +of types \cite{Vox}. Ultimately, the inspiration for the Didone +types is the `Romain du Roi', the type that was designed by +Nicolas Jaugeon around 1692 for the French Imprimerie Royale. + +Didone types are characterized by a strong vertical orientation, +and thin hairlines. The vertical accent is strengthened by the +fact that the insides of curves are flattened. +The result is a clear and brilliant page, provided that the +printing is done carefully and on good quality paper. +\message{Reference format} +However, they are quite vulnerable; \cite{Up} +compares them to the distinguished but fragile furniture +from the same period, saying one is afraid to use either, +`for both seem in danger of breaking in pieces'. +With the current proliferation of low resolution (around +300 dot per inch) printers, the Computer Modern is +a somewhat unfortunate choice. + +Recently, Donald Knuth has developed +a new typeface (or rather, a subfamily of typefaces) +by changing parameters +in the Computer Modern family. The result is a so-called +`Egyptian' typeface: Computer Concrete \cite{K:cc}. +The name derives from the +fact that it was intended primarily for the book {\italic Concrete +Mathematics}. Egyptian typefaces (they fall under the `M\'ecanes' +in the Vox classification, meaning constructed, +not derived from written letters) have a very uniform line width +and square serifs. They do not have anything to do with Egypt; +such types happened to be popular in the first half of the nineteenth +century when Egyptology was developing and popular. + +%\point \TeX\ and web +\section{\TeX\ and web} + +The \TeX\ program is written in \web, a programming language +\term \web\par\term Pascal\par +that can be considered as a subset of Pascal, augmented with +a preprocessor. + +\TeX\ makes no use of some features of Pascal, in order to +facilitate porting to Pascal systems other than the one +it was originally designed for, and even to enable automatic +translation to other programming languages such as~C. +For instance, it does not use the Pascal \n{With} construct. +Also, procedures do not have output parameters; apart from +writing to global variables, the only way +values are returned is through +\n{Function} values. + +Actually, \web\ is more than a superset of a subset of Pascal +(and to be more precise, it can also be used with other +programming languages); +it is a `system of structured documentation'. This means that +the \web\ programmer writes pieces of program code, +interspersed with their documentation, in one file. +This idea of `literate programming' was +introduced in~\cite{K:literate}; +for more information, see~\cite{Sewell}. + +Two auxiliary programs, +Tangle and Weave, can then be used to strip the documentation +and convert \web\ into regular Pascal, or to convert the +\web\ file into a \TeX\ file that will typeset the program +and documentation. + +Portability of \web\ programs is achieved by the `change file' +mechanism. A~change file is a list of changes to be made to +the \web\ file; a~bit like a stream editor script. +These changes can comprise both adaptations of the \web\ file +to the particular Pascal compiler that will be used, and +bug fixes to \TeX. Thus the \n{TeX.web} file need never be edited. + + +%\point The \TeX\ Users Group +\section{The \TeX\ Users Group} + +\TeX\ users have joined into several users groups +\term TUG\par +over the last decade. Many national or language +users groups exist, and a lot of them publish newsletters. +The oldest of all \TeX\ users groups is simply called +that: the \TeX\ Users Group, or TUG, +and its journal is called {\italic TUGboat}\term TUGboat\par. +You can reach them at +\begin{disp} \TeX\ Users Group\nl P.O. Box 2311\nl + Portland, OR 97208-2311, USA +\end{disp} + or electronically at \n{office@tug.org} on the Internet. + + +%%%% end of input file [run] + +%\InputFile:trace +%%%% this is input file [trace] +%\subject[trace] Tracing +\endofchapter +\chapter{Tracing}\label{trace} + +\TeX's workings are often quite different from what +\term tracing\par\term statistics\par +the programmer expected, so there are ways to discover how \TeX\ +arrived at the result it did. The \cs{tracing...} +commands write +all information of a certain kind to the log file +(and to the terminal if \cs{tracingonline} is positive), +and a number of \cs{show...} commands can be used to ask the +current status or value of various items of \TeX. + +In the following list, only \cs{show} and \cs{showthe} +display their output on the terminal by default, +other \cs{show...} and \cs{tracing...} commands +write to the log file. They will write in addition to +the terminal if \cs{tracingonline} is positive. + +\begin{inventory} +\item [\cs{meaning}] + Give the meaning of a control sequence as a string of characters. + +\item [\cs{show}] + Display the meaning of a control sequence. + +\item [\cs{showthe}] + Display the result of prefixing a token with \cs{the}. + +\item [\cs{showbox}] + Display the contents of a box. + +\item [\cs{showlists}] + Display + the contents of the partial lists + currently built in all modes. + This is treated on + page~\pageref{showlists}. + +\item [\csidx{tracingcommands}] + If this is~1 \TeX\ displays primitive commands executed; + if this is 2~or more the outcome of conditionals is also recorded. + +\item [\csidx{tracingmacros}] + If this is~1, \TeX\ shows expansion of macros + that are performed and the actual values of the arguments; + if this is 2~or more \gr{token parameter}s such as + \cs{output} and \cs{everypar} are also traced. + +\item [\cs{tracingoutput}] + If this is positive, the log file shows a dump of boxes + that are shipped to the \n{dvi} file. + +\item [\cs{showboxdepth}] + The number of levels of box dump that are shown when + boxes are displayed. + +\item [\cs{showboxbreadth}] + Number of successive elements on each level that are shown when + boxes are displayed. + +\item [\csidx{tracingonline}] + If this parameter is positive, \TeX\ will write trace + information to the terminal in addition to the log file. + +\item [\cs{tracingparagraphs}] + If this parameter is positive, \TeX\ generates + a trace of the line breaking algorithm. + +\item [\csidx{tracingpages}] + If this parameter is positive, \TeX\ generates + a trace of the page breaking algorithm. + +\item [\csidx{tracinglostchars}] + If this parameter is positive, \TeX\ gives + diagnostic messages whenever a character is accessed that + is not present in a font. + Plain default:~1. + +\item [\csidx{tracingrestores}] + If this parameter is positive, \TeX\ will report + all values that are restored when a group ends. + +\item [\cs{tracingstats}] + If this parameter is~1, \TeX\ reports at the + end of the job the usage of various internal arrays; + if it is~2, the memory demands are given whenever + a page is shipped out. + +\end{inventory} + +%\point Meaning and content: \cs{show}, \cs{showthe}, \cs{meaning} +\section{Meaning and content: \protect\cs{show}, \protect\cs{showthe}, \protect\cs{meaning}} + +The meaning of control sequences, and the contents of those +that represent internal quantities, can be obtained +by the primitive commands \cs{show}, \cs{showthe}, +and~\cs{meaning}. + +The control sequences \cs{show} and \cs{meaning} are similar: +\alt +the former will give +\cstoidx show\par\cstoidx meaning\par +output to the log file and the terminal, whereas the latter +will produce the same tokens, but they are placed in \TeX's +input stream. + +The meaning of a primitive command of \TeX\ is that command itself: +\begin{verbatim} +\show\baselineskip +\end{verbatim} +gives +\begin{verbatim} +\baselineskip=\baselineskip +\end{verbatim} +The meaning of a defined quantity is its definition: +\begin{verbatim} +\show\pageno +\end{verbatim} +gives +\begin{verbatim} +\pageno=\count0 +\end{verbatim} +The meaning of a macro is its parameter text and replacement text: +\begin{verbatim} +\def\foo#1?#2\par{\set{#1!}\set{#2?}} +\show\foo +\end{verbatim} +gives +\begin{verbatim} +\foo=macro: +#1?#2\par ->\set {#1!}\set {#2?} +\end{verbatim} +For macros without parameters the part before the arrow +(the parameter text) is empty. + +The \csidx{showthe} command will display on the log file and terminal +the tokens that \cs{the} produces. +After \cs{show}, \cs{showthe}, \cs{showbox}, and \cs{showlists} +\TeX\ asks the user for input; this can be prevented +by specifying \cs{scrollmode}. +Characters generated +by \cs{meaning} and \cs{the} have category~12, except for spaces +(see page~\pageref{cat12}); +the value of \cs{escapechar} is used when control sequences +are represented. + +%\point Show boxes: \cs{showbox}, \cs{tracingoutput} +\section{Show boxes: \protect\cs{showbox}, \protect\cs{tracingoutput}} + +If \cs{tracingoutput} is positive the log file will +\cstoidx tracingoutput\par\cstoidx showbox\par +receive a dumped representation of all boxes that are +written to the \n{dvi} file with \cs{shipout}. +The same representation is used +by the command \cs{showbox}\gr{8-bit number}. + +In the first case \TeX\ will report `Completed box being shipped out'; +in the second case it will enter \cs{errorstopmode}, and +tell the user `OK. (see the transcript file)'. +If \cs{tracingonline} is positive, the box is also displayed +on the terminal; if \cs{scrollmode} has been specified, +\TeX\ does not stop for input. + +The upper bound on the +number of nested boxes that is dumped is \cs{showboxdepth}; +\cstoidx showboxdepth\par\cstoidx showboxbreadth\par +each time a level is visited at most \cs{showboxbreadth} +items are shown, the remainder of the list is summarized +with~\n{etc.} +For each box its height, depth, and width +are indicated in that order, and for characters it is +stated from what font they were taken. + +\begin{example} After +\begin{verbatim} +\font\tenroman=cmr10 \tenroman +\setbox0=\hbox{g} +\showbox0 +\end{verbatim} +the log file will show +\begin{verbatim} +\hbox(4.30554+1.94444)x5.00002 +.\tenroman g +\end{verbatim} +indicating that the box was \n{4.30554pt} high, +\n{1.94444pt} deep, and \n{5.00002pt} wide, and that it contained +a character `g' from the font \cs{tenroman}. +Note that the fifth decimal of all sizes may be rounded +because \TeX\ works with multiples of $2^{-16}$\n{pt}. +\message{ifmath: scriptfont fam0 fill!} +\end{example} + +The next example has nested boxes, +\begin{verbatim} +\vbox{\hbox{g}\hbox{o}} +\end{verbatim} +and it contains \cs{baselineskip} glue between the boxes. +After a \cs{showbox} command the log file output is: +\begin{verbatim} +\vbox(16.30554+0.0)x5.00002 +.\hbox(4.30554+1.94444)x5.00002 +..\tenroman g +.\glue(\baselineskip) 5.75002 +.\hbox(4.30554+0.0)x5.00002 +..\tenroman o +\end{verbatim} +Each time a new level is entered an extra dot is added to +the front of the line. Note that \TeX\ tells explicitly +that the glue is \cs{baselineskip} glue; +it inserts names like this for all automatically inserted glue. +The value of +the baselineskip glue here is such that the baselines of +the boxes are at 12 point distance. + +Now let us look at explicit (user) glue. \TeX\ indicates the ratio +by which it is stretched or shrunk. + +\begin{example}s +\begin{verbatim} +\hbox to 20pt {\kern10pt \hskip0pt plus 5pt} +\end{verbatim} +gives (indicating that the available stretch has been +multiplied by~\n{2.0}): +\begin{verbatim} +\hbox(0.0+0.0)x20.0, glue set 2.0 +.\kern 10.0 +.\glue 0.0 plus 5.0 +\end{verbatim} +and +\begin{verbatim} +\hbox to 0pt {\kern10pt \hskip0pt minus 20pt} +\end{verbatim} +gives (the shrink has been multiplied by~\n{0.5}) +\begin{verbatim} +\hbox(0.0+0.0)x0.0, glue set - 0.5 +.\kern 10.0 +.\glue 0.0 minus 20.0 +\end{verbatim} +respectively. +\end{example} + +This is an example with infinitely stretchable or shrinkable +glue: +\begin{verbatim} +\hbox(4.00000+0.14000)x15.0, glue set 9.00000fil +\end{verbatim} +This means that the horizontal box contained \n{fil} glue, and +it was set such that its resulting width was \n{9pt}. + +Underfull boxes are dumped like all other boxes, but +the usual `\n{Underfull hbox detected at line...}' +is given. Overfull horizontal boxes contain a vertical rule +of width \cs{overfullrule}: +\begin{verbatim} +\hbox to 5pt {\kern10pt} +\end{verbatim} +gives +\begin{verbatim} +\hbox(0.0+0.0)x5.0 +.\kern 10.0 +.\rule(*+*)x5.0 +\end{verbatim} + + +Box leaders are not dumped completely: +\begin{verbatim} +.\leaders 40.0 +..\hbox(4.77313+0.14581)x15.0, glue set 9.76852fil +...\tenrm a +...\glue 0.0 plus 1.0fil +\end{verbatim} +is the dump for +\begin{verbatim} +\leaders\hbox to 15pt{\tenrm a\hfil}\hskip 40pt +\end{verbatim} +Preceding or trailing glue around the leader +boxes is also not indicated. + +%\point Global statistics +\section{Global statistics} + +The parameter \csidx{tracingstats} can be used to force \TeX\ +to report at the end of the job the global use of resources. +Some production versions of \TeX\ may not have this option. + +As an example, here are the statistics for this book: +\begin{verbatim} +Here is how much of TeX's memory you used: +\end{verbatim} +String memory (bounded by `pool size'): +\begin{verbatim} + 877 strings out of 4649 + 9928 string characters out of 61781 +\end{verbatim} +Main memory, control sequences, font memory: +\begin{verbatim} + 53071 words of memory out of 262141 + 2528 multiletter control sequences out of 9500 + 20137 words of font info for 70 fonts, + out of 72000 for 255 +\end{verbatim} +Hyphenation: +\begin{verbatim} + 14 hyphenation exceptions out of 607 +\end{verbatim} +Stacks: input, nest, parameter, buffer, and save stack respectively, +\begin{verbatim} + 17i,6n,19p,245b,422s stack positions out of + 300i,40n,60p,3000b,4000s +\end{verbatim} + +% \begin{comment} +% \endinput + +% %\point Line breaking: \cs{tracingparagraphs} +% \section{Line breaking: \cs{tracingparagraphs}} + +% If \cs{tracingparagraphs} is positive, \TeX's line breaking +% \cstoidx tracingparagraphs\par +% algorithm will generate trace output. However, on some \TeX\ +% implementations this trace mode may have been disabled to get a +% faster running system. + +% Consider an example paragraph of \TeX: +% \begin{verbatim} +% \hsize=3in \parindent=0cm \frenchspacing +% \pretolerance=500 +% This is a sample paragraph to show the trace output that +% \TeX's line breaking algorithm produces. Some \TeX\ systems +% cannot generate this trace, as the relevant piece of code +% has been commented out for speed optimisation. +% With ever faster computers this won't be necessary any more. +% \end{verbatim} + +% \TeX\ first attempts to break the paragraph without +% hyphenation, and it will accept solutions where each +% line has a badness less than \cs{pretolerance}. +% \begin{verbatim} +% @firstpass +% \end{verbatim} Report that the first pass has started; +% \begin{verbatim} +% []\tenrm This is a sample paragraph to show the trace +% \end{verbatim} +% Apparently this is the only way to fill the first line; +% \begin{verbatim} +% @ via @@0 b=263 p=0 d=84529 +% \end{verbatim} and doing so +% had badness~263, a zero penalty, and a resulting 84529 +% demerit points. +% \begin{verbatim} +% @@1: line 1.0 t=84529 -> @@0 +% \end{verbatim} Conclusion: +% breakpoint~1 (\verb>@@1>) occurs on line~1, and it makes the +% line `very loose' (indicated by the~\n{.0}), +% and the total demerits are +% 84529 if the previous breakpoint was number~0. + +% The first pass is now aborted. +% \begin{verbatim} +% @secondpass +% []\tenrm This is a sam-ple para-graph to show the trace out- +% @\discretionary via @@0 b=2 p=50 d=2644 +% @@1: line 1.2- t=2644 -> @@0 +% \end{verbatim} +% With a very small badness of~2, but with 50 penalty points +% for breaking at a hyphen, this line is `decent' +% (indicated by the~\n{.2}), and the total of demerit points +% is~2644. + +% The second line is also straighforward: +% \begin{verbatim} +% put that T[]X's line break-ing al-go-rithm pro-duces. +% @ via @@1 b=0 p=0 d=100 +% @@2: line 2.2 t=2744 -> @@1 +% \end{verbatim} +% The demerits now derive solely from the \cs{linepenalty}, +% which is~10. Similarly the third line: +% \begin{verbatim} +% Some T[]X sys-tems can-not gen-er-ate this trace, as +% @ via @@2 b=1 p=0 d=121 +% @@3: line 3.2 t=2865 -> @@2 +% \end{verbatim} + +% For the fourth line two possibilities exist: +% it can be set `loose' with 9409 demerit points +% \begin{verbatim} +% the rel-e-vant piece of code has been com-mented +% @ via @@3 b=87 p=0 d=9409 +% @@4: line 4.1 t=12274 -> @@3 +% \end{verbatim} +% or, fitting in an extra word, it can be set `tight' with +% 2601 demerit points +% \begin{verbatim} +% out +% @ via @@3 b=41 p=0 d=2601 +% @@5: line 4.3 t=5466 -> @@3 +% \end{verbatim} + +% Line 5 can be set in three ways: +% coming from breakpoint~4 it can be broken as +% \begin{verbatim} +% for speed op-ti-mi-sa-tion. With ever faster com- +% @\discretionary via @@4 b=0 p=50 d=2600 +% @@6: line 5.2- t=14874 -> @@4 +% \end{verbatim} +% and coming from breakpoint~5 there are two ways: +% \begin{verbatim} +% put- +% @\discretionary via @@5 b=2 p=50 d=2644 +% @@7: line 5.2- t=8110 -> @@5 +% \end{verbatim} +% and \begin{verbatim} +% ers +% @ via @@5 b=84 p=0 d=8836 +% @@8: line 5.3 t=14302 -> @@5 +% \end{verbatim} +% Of the three, the last possibility is the only one that +% does not involve hyphenating line~5. + +% As line 6 is the last line of the paragraph, coming from +% breakpoints 6 or~7 gives an extra 5000 demerit points +% from the \cs{finalhyphendemerits}. +% \begin{verbatim} +% this won't be nec-es-sary any more. +% @\par via @@6 b=0 p=-10000 d=5100 +% @\par via @@7 b=0 p=-10000 d=5100 +% @\par via @@8 b=0 p=-10000 d=100 +% @@9: line 6.2- t=13210 -> @@7 +% \end{verbatim} +% However, coming from breakpoint 7 still gives the least +% demerits. + +% \end{comment} +%%%% end of input file [trace] + +%\InputFile:errors +%%%% this is input file [errors] +%\subject[error] Errors, Catastrophes, \nl and Help +\endofchapter +\chapter{Errors, Catastrophes, and Help}\label{error} + +When \TeX\ is running, various errors can occur. +This chapter treats how errors in the input are displayed, +and what sort of overflow of internal data structures +of \TeX\ can occur. + +\begin{inventory} +\item [\cs{errorcontextlines}] + (\TeX3 only) + Number of additional context lines shown in error messages. + +\item [\cs{errmessage}] + Report an error, giving the parameter of this command as message. + +\item [\cs{errhelp}] + Tokens that will be displayed if the user + asks further help after an \cs{errmessage}. + +\end{inventory} + +%\point Error messages +\section{Error messages} + +When \TeX\ is running in \cs{errorstopmode} (which it usually is; +see Chapter~\ref{run} for the other running modes), +errors occurring are reported on the user terminal, and \TeX\ +asks the user for further instructions. +Errors can occur either because of some internal condition +of \TeX, or because a macro has issued an \csidx{errmessage} +command. + +If an error occurs \TeX\ shows the input +\term error patching\par +line +on which the error occurred. If the offending command was +not on that line but, for instance, in a macro that was +called \ldash possibly indirectly \rdash from that line, +the line of that command is also shown. +If the offending command was indirectly called, +an additional \csidx{errorcontextlines} number of lines +is shown with the preceding macro calls. + +A~value of \cs{errorcontextlines}${}=0$ causes \n{...} +to be printed as the sole indication that there is a context. +Negative values inhibit even this. + +For each macro in the sequence that leads to the offending +command, +\TeX\ attempts to display some +preceding and some following tokens. +First one line is displayed ending with +the \ldash indirectly \rdash offending command; then, one line lower +some following tokens are given. + +\begin{example} +\begin{verbatim} +This paragraph ends \vship1cm with a skip. +\end{verbatim} +gives +\begin{verbatim} +! Undefined control sequence. +l.1 This paragraph ends \vship + 1cm with a skip. +\end{verbatim} +\end{example} + +If \TeX\ is not running in some non-stop mode\label{interaction}, +the user is given the chance to patch errors or to +ask for further information. In general the following +options are available:\begin{description}\item [\gr{return}] +\TeX\ will continue processing. If the error was something +innocent that \TeX\ could either ignore or patch itself, +this is the easy way out. +\item [\n h] +Give further details about the error. +If the error was caused by an \cs{err\-message} command, +the \csidx{errhelp} tokens will be displayed here. +\item [\n i] +Insert. The user can insert some material. For example, +if a control sequence is misspelled, the correct command can +sometimes be inserted, as \begin{verbatim} +i\vskip +\end{verbatim} +for the above +example. Also, this is an opportunity for inserting +\cs{show} commands to inspect \TeX's internal state. +However, if \TeX\ is in the middle of +scanning something complicated, +such commands will not be executed, or will even +add to the confusion. +\item [\n s] + (\cs{scrollmode}) +Scroll further errors, but display the messages. +\TeX\ will patch any further errors. +This is a handy option, for instance if the error occurs +in an alignment, because the number of subsequent errors tends +to be rather large. +\item [\n r] + (\cs{nonstopmode}) +Run without stopping. \TeX\ will never stop for user interaction. +\item [\n q] + (\cs{batchmode}) +Quiet running. \TeX\ will never stop for user interaction, +and does not give any more terminal output. +\item [\n x] +Exit. Abort this run of \TeX. +\item [\n e] +Edit. This option is not available on all \TeX\ system. +If it is, the run of \TeX\ is aborted, and an editor is +started, opening with the input file, maybe even +on the offending line. +\end{description} + + +%\point Overflow errors +\section{Overflow errors} + +Harsh reality imposes some restrictions on how elaborate +\term overflow errors\par +\TeX's workings can get. Some restrictions are imposed by +compile-time constants, and are therefore fairly loose, but +some depend strongly on the actual computer implementation. + +Here follows the list of all categories of overflow that +prompt \TeX\ to report `Capacity exceeded'. +Most bounds involved are (determined by) compile-time +constants; their values given here in parentheses are those +used in the source listing of \TeX\ in~\cite{Knuth:TeXbook}. +Actual values may differ, and probably will. Remember +that \TeX\ was developed in the good old days when even +big computers were fairly small. + +%\spoint Buffer size {\rm(500)} +\subsection{Buffer size {\rm(500)}} + +Current lines of all files that are open are kept in +\TeX's input buffer, as are control sequence names +that are being built with \verb-\csname...\endcsname-. + +%\spoint Exception dictionary {\rm(307)} +\subsection{Exception dictionary {\rm(307)}} + +The maximum number of hyphenation exceptions specified +by \cs{hyphenation} must be a prime number. +Two arrays with this many halfwords are allocated. + +Changing this number makes formats incompatible; +that is, \TeX\ can only use a format that was made by +an \IniTeX\ with the same value for this constant. + +%\spoint Font memory (20$\,$000) +\subsection{Font memory (20$\,$000)} + +Information about fonts is stored in an array of +memory words. This is easily overflowed by preloading too +many fonts in \IniTeX. + +%\spoint Grouping levels +\subsection{Grouping levels} + +The number of open groups should be recordable +in a quarter word. There is no compile-time constant corresponding +to this. + +%\spoint Hash size {\rm(2100)} +\subsection{Hash size {\rm(2100)}} + +Maximum number of control sequences. It is suggested that +this number should not exceed 10\% of the main memory size. +The values in \TeX\ and \IniTeX\ should agree; also the +\n{hash\_prime} values should agree. + +This value is rather low; for macro packages that are more +elaborate than plain \TeX\ a value of about 3000 is more +realistic. + +%\spoint Number of strings {\rm(3000)} +\subsection{Number of strings {\rm(3000)}} + +The maximum number of strings must be recordable in a half word. + +%\spoint Input stack size {\rm(200)} +\subsection{Input stack size {\rm(200)}} + +For each input source an item is allocated on the input stack. +Typical input sources are input files (but their simultaneous +number is more limited; see below), and token lists +such as token variables, macro replacement texts, and +alignment templates. A~macro with `runaway recursion' +(for example, \verb>\def\mac{{\mac}}>) +will overflow this stack. + +\TeX\ performs some optimization here: before the last call +in a token list all token lists ending with this call are +cleared. This process is +similar to `resolving tail recursion' (see Chapter~\ref{macro}). + +%\spoint Main memory size (30$\,$000) +\subsection{Main memory size (30$\,$000)} + +Almost all `dynamic' objects of \TeX, such as macro definition +texts and all material on the current page, +are stored in the main memory array. +Formats may already take $20\,000$ words of +main memory for macro definitions, and complicated pages containing +for instance the \LaTeX\ picture environment may easily +overflow this array. + +\TeX's main memory is divided in words, and a half word +is supposed to be able to address the whole of the memory. +Thus on current 32-bit computers the most common choice +is to let the main memory size be at most 64K bytes. +A~half word address can then be stored in 16 bits, +half a machine word. + +However, so-called `Big \TeX' implementations exist +\term big \TeX\par +that have a main memory larger than 64K words. +Most compilers will then allocate 32-bit words for +addressing this memory, even if (say) 18 bits would +suffice. Big \TeX s therefore become immediately +a lot bigger when they cross the 64K threshold. +Thus they are usually not found on microcomputers, +although virtual memory schemes for these are possible; +see for instance~\cite{Thull}. + +\TeX\ can have a bigger main memory than \IniTeX; +see Chapter~\ref{TeXcomm} for further details. + +%\spoint Parameter stack size {\rm(60)} +\subsection{Parameter stack size {\rm(60)}} + +Macro parameters may contain macro calls with +further parameters. The number of parameters that may occur +nested is bounded by the parameter stack size. + +%\spoint Pattern memory {\rm(8000)} +\subsection{Pattern memory {\rm(8000)}} + +Hyphenation patterns are stored in a trie array. +The default size of 8000 hyphenation patterns seems sufficient +for English or Italian, for example, but it is not for +Dutch or German. + +%\spoint Pattern memory ops per language +\subsection{Pattern memory ops per language} + +The number of hyphenation ops (see the literature about +hyphenation: \cite{Liang} and appendix~H of~\cite{Knuth:TeXbook}) +should be recordable +in a quarter word. There is no compile-time constant corresponding +to this. \TeX\ version~2 had the same upper bound, but gave no +error message in case of overflow. Again, for languages such +as Dutch and German this bound is too low. +There are versions of \TeX\ that have a higher bound here. + +%\spoint Pool size (32$\,$000) +\subsection{Pool size (32$\,$000)} + +Strings are error messages and control sequence names. +They are stored using one byte per character. +\TeX\ has initially about $23\,000$ characters worth of +strings. + +The pool will overflow if a user defines a large number of +control sequences on top of a substantial macro package. +However, even if the user does not define any new commands +\mdqon +overflow may occur: cross"-referencing schemes also +\mdqoff +work by defining control sequences. For large documents +a pool size of $40\,000$ or $60\,000$ is probably sufficient. + +%\spoint Save size {\rm(600)} +\subsection{Save size {\rm(600)}} + +Quantities that are assigned to inside a group must be +restored after the end of that group. +The save stack is where the values to be restored are kept; +the size of the +save stack limits the number of values that can be restored. + +Alternating global and local assignments to a value +will lead to `save stack build-up': for each local +assignment following a global assignment the +previous value of the variable is saved. Thus an +alternation of such assignments will lead to +an unnecessary proliferation of items on the save stack. + +%\spoint Semantic nest size {\rm(40)} +\subsection{Semantic nest size {\rm(40)}} + +Each time \TeX\ switches to a mode nested inside another +mode (for instance when processing an \verb-\hbox- inside +a \verb-\vbox-) the current state is pushed on the +semantic nest stack. The semantic nest size is the maximum +number of levels that can be pushed. + +%\spoint Text input levels {\rm(6)} +\subsection{Text input levels {\rm(6)}} + +The number of nested \verb-\input- files +has to be very limited, +as the current lines are all kept in the input buffer. + +%%%% end of input file [errors] + +%\InputFile:syntax +%%%% this is input file [syntax] +%\subject[gramm] The Grammar of \TeX +\endofchapter +\chapter{The Grammar of \TeX}\label{gramm} + +Many chapters in this book contain pieces of the +grammar that defines the formal syntax of \TeX. +In this chapter the structure of the rewriting rules of the +grammar is explained, and some key notions are presented. + +In \TeXbook\ a grammar appears in Chapters~24--27. +An even more rigorous grammar of \TeX\ can be found in~\cite{Appelt}. +The grammar presented in this book is virtually identical +to that of \TeXbook. + +%\point Notations +\section{Notations} + +Basic to the grammar are \begin{description}\item [grammatical terms] +These are enclosed in angle brackets:\begin{disp}\gr{term}\end{disp} +\item [control sequences] +These are given in typewriter type with a backslash for +the escape character:\begin{disp}\cs{command}\end{disp} +\end{description} +Lastly there are \begin{description}\item [keywords] +Also given in typewriter type\begin{disp}\n{keyword}\end{disp} +This is a limited collection of words that have a special +meaning for \TeX\ in certain contexts; see below.\end{description} + +The three elements of the grammar are used in syntax rules: +\begin{disp}\gr{snark} $\longrightarrow$ \n{boojum} $|$ \gr{empty} +\end{disp} +This rule says that the grammatical entity \gr{snark} +is either the keyword \n{boojum}, or the grammatical +entity \gr{empty}. + +There are two other notational conventions. +The first is that the double quote +is used to indicate hexadecimal (base~16) notation. +For instance \verb>"ab56> stands for $10\times16^3+11\times16^2 ++5\times16^1+6\times16^0$. The second convention +is that subscripts are used to denote category codes. +Thus \n{a}$_{12}$ denotes an `a' of category~12. + +%\point[keywords] Keywords +\section{Keywords} +\label{keywords} + +A keyword is sequence of characters (or character tokens) +\term keywords\par +of any category code but~13 (active). +Unlike the situation in control sequences, \TeX\ does not +distinguish between lowercase and uppercase characters +in keywords. Uppercase characters in keywords are converted to +lowercase by adding 32 to them; the \cs{lccode} and \cs{uccode} +are not used here. Furthermore, any keyword can be preceded by +optional spaces. + +Thus both \n{true cm} and \n{truecm} are legal. +By far the strangest example, however, is provided +by the grammar rule +\begin{disp}\gr{fil unit} $\longrightarrow$ \n{fil} $|$ \gr{fil unit}\n l +\end{disp} which implies that \hbox{\n{fil L l}} is also +a legal \gr{fil dimen}. Strange errors can ensue from this; +see page~\pageref{fil:l:l} for an example. + +Here is the full list of all keywords: \n{at}, \n{bp}, +\n{by}, \n{cc}, \n{cm}, \n{dd}, \n{depth}, \n{em}, \n{ex}, +\n{fil}, \n{height}, \n{in}, \n l, \n{minus}, \n{mm}, \n{mu}, +\n{pc}, \n{plus}, \n{pt}, \n{scaled}, \n{sp}, \n{spread}, +\n{to}, \n{true}, \n{width}. + +%\point Specific grammatical terms +\section{Specific grammatical terms} + +Some grammatical terms appear in a lot of rules. +One such term is \gr{optional spaces}. It is probably +\term space, optional\par +clear what is meant, but here is the formal definition: +\begin{disp}\gr{optional spaces} $\longrightarrow$ + \gr{empty} $|$ \gr{space token}\gr{optional spaces} + \end{disp} +which amounts to saying that \gr{optional spaces} +is zero or more space tokens. + +Other terms may not be so immediately obvious. +Below are some of them. + +%\spoint \gr{equals} +\subsection{\gr{equals}} + +In assignments the equals sign is optional; therefore there +is a term +\begin{disp}\gr{equals} $\longrightarrow$ \gr{optional spaces} + $|$ \gr{optional spaces}$=_{12}$\end{disp} +in \TeX's grammar. +%% \begin{comment} +%% One assignment exists where the equals sign cannot +%% be left out: +%% \begin{verbatim} +%% \let\spacetoken= %assign a space +%% \end{verbatim} +%% Here the space would have been skipped in \TeX's input processor +%% if the equals sign had been left out. +%% \end{comment} + +%\spoint \gr{filler}, \gr{general text} +\subsection{\gr{filler}, \gr{general text}} + +More obscure than the \gr{optional spaces} is the combination +of spaces and \cs{relax} tokens that is allowed +in some places, for instance +\begin{verbatim} +\setbox0= \relax\box1 +\end{verbatim} +The quantity involved is +\begin{disp}\gr{filler} $\longrightarrow$ \gr{optional spaces} + $|$ \gr{filler}\cs{relax}\gr{optional spaces}\end{disp} +One important occurrence of \gr{filler} is in +\begin{disp}\gr{general text} $\longrightarrow$ + \gr{filler}\lb\gr{balanced text}\gr{right brace} + \end{disp} +A \gr{general text} follows such control sequences as +\cs{message}, \cs{uppercase}, or \cs{mark}. The braces around +the \gr{balanced text} are explained in the next point. + +%\spoint \lb\rb\ and \gr{left brace}\gr{right brace} +\subsection{\lb\rb\ and \gr{left brace}\gr{right brace}} + +The \TeX\ grammar uses a perhaps somewhat unfortunate +convention for braces. First of all \begin{disp}\lb\ and \rb\end{disp} +stand for braces that are either explicit open/close group +characters, or control sequences defined by \cs{let}, +such as \begin{verbatim} +\let\bgroup={ \let\egroup=} +\end{verbatim} +The grammatical terms \begin{disp}\gr{left brace} and \gr{right brace} +\end{disp} stand for explicit open/close group characters, +that is, characters of categories 1 and~2 respectively. + +Various combinations of these two kinds of braces exist. +Braces around boxes can be implicit: +\begin{disp}\cs{hbox}\gr{box specification}\lb + \gr{horizontal mode material}\rb\end{disp} +Around a macro definition there must be explicit braces: +\begin{disp}\gr{definition text} $\longrightarrow$ + \gr{parameter text}\gr{left brace}\gr{balanced text}\gr{right brace} + \end{disp} +Finally, the \gr{general text} that was mentioned above +has to be explicitly closed, but it can be implicitly opened: +\begin{disp}\gr{general text} $\longrightarrow$ + \gr{filler}\lb\gr{balanced text}\gr{right brace} + \end{disp} +The closing brace of a \gr{general text} has to be explicit, +since a general text is a token list, which may +contain \cs{egroup} tokens. +\TeX\ performs expansion to find the opening +brace of a \gr{general text}. + +%\spoint \gr{math field} +\subsection{\gr{math field}} + +In math mode various operations such as subscripting +or applying \cs{underline} take an argument that +is a \gr{math field}: either a single symbol, or +a group. Here is the exact definition. +\begin{disp}\gr{math field} $\longrightarrow$ + \gr{math symbol} $|$ \gr{filler}\lb\gr{math mode material}\rb\nl + \gr{math symbol} $\longrightarrow$ \gr{character} $|$ + \gr{math character} +\end{disp} +See page~\pageref{character} for \gr{character}, +\alt +and page~\pageref{math:character} for \gr{math character}. + +%\point[2vs3] Differences between \TeX\ versions 2 and 3 +\section{Differences between \TeX\ versions 2 and 3} +\label{2vs3} + +In 1989 Knuth released \TeX\ version~3.0, which is +\term \protect\TeX\ version 2\par +the first real change in \TeX\ since version~2.0, +which was released in~1986 (version~0 of \TeX\ was +released in 1982; see~\cite{Knuth:TeXerrors} for more about +the history of \TeX). +All intermediate versions were merely bug fixes. + +The main difference between versions 2~and~3 lies +in the fact that 8-bit input has become possible. +Associated with this, various quantities that +used to be 127 or~128 have been raised to 255 +or~256 respectively. Here is a short list. +The full description is in~\cite{K:TeX23}. + +\begin{itemize}\message{Remove other TeX3 refernces!} +\item All `codes' (\cs{catcode}, \cs{sfcode}, et cetera; + see page~\pageref{codename}) + now apply to 256 character codes instead of~128. +\item A character with code \cs{endlinechar} + is appended to the line unless this parameter is negative +or more than~255 (this was~127) (see page~\pageref{append:elc}). +\item No escape character is output by \cs{write} and + other commands if \cs{escapechar} is negative or more than~255 +(this was~127) (see page~\pageref{use:escape}). +\item The \verb>^^> replacement mechanism has been extended + (see page~\pageref{hathat}). +\item Parameters \cs{language}, \cs{inputlineno}, + \cs{errorcontextlines}, \cs{lefthyphenmin}, \cs{righthyphenmin}, +\cs{badness}, \cs{holdinginserts}, \cs{emergencystretch}, +and commands \cs{noboundary}, \cs{setlanguage} +have been added. +\item The value of \cs{outputpenalty} is no longer zero + \alt + if the page break was not at a penalty item; + instead it is~$10\,000$ (see page~\pageref{break:penalty}). +\end{itemize} + +The plain format has also been updated, mostly +\alt +with default settings for parameters such as +\cs{lefthyphenmin}, but also a few macros have been added. + +\endofchapter +%%%% end of input file [syntax] + +\chapter{Glossary of \TeX\ Primitives} +\begin{raggedright} +\input glossary +\end{raggedright} +\endofchapter + +\chapter{Tables}\label{table} +\pagestyle{plain} +\clearpage +\input tables +\endofchapter + +%\chapter{Index} + +\printindex +%\input \jobname.ind +%\endofchapter % this winds up on a page of its own. + +%\chapter{References} +\mdqon +\bibliography{tex} +\bibliographystyle{plain} +\mdqoff +\endofchapter + +%%%% end of input file [tables] + +\chapter*{Change log} + +\section*{Version 1.1} + +Small remark about \cs{afterassignment} after macro definitions. + +Trouble with indexing macros fixed, I hope. + +Separate letter and a4 versions. + +Better intro for the chapter \ref{space} on spacing. + +\end{document} + +\HasNum:no \ToVerso +\asubject List of Examples\par +\message{set a counter here!}%\SetCounter:point=0 +\def\subjectTitle{List of Examples} +\makeatletter\refresh@mark@item{subjectTitle}{LIST OF EXAMPLES} +\makeatother + +\LoadExternalFile:todo +\EjectPage + +\asubject Index by Command\par +\def\subjectTitle{INDEX BY COMMAND} +\makeatletter\refresh@mark@item{subjectTitle}{INDEX BY COMMAND} +\makeatother +\GutterWidth=1.5pc \NumberOfColumns:3 +\LoadExternalFile:index +\EjectPage + +\begin{comment} +\message{set a counter here!}%\SetCounter:Page=306 \CounterRepresentation:Page=1 +\HasNum:no +\SerifFont %\pointsize:9 \Style:roman +\section{size:9 \Style:roman} +\flushright:no \hyphenpenalty=-50 + +\asubject Index by Topic\par +\def\subjectTitle{INDEX BY TOPIC} +\makeatletter\refresh@mark@item{subjectTitle}{INDEX BY TOPIC} +\makeatother +\GutterWidth=1.5pc \NumberOfColumns:3 +%\GutterWidth=2pc \NumberOfColumns:2 +\message{reg: medskips, \string\n{..}, balance} +\SetListIndent:1=2em +\SetListIndent:2=1em +\LoadExternalFile:register + +\Stop |