From 0e03b1c035f50863fd828faf12e59f1b3c6850a7 Mon Sep 17 00:00:00 2001 From: Norbert Preining Date: Thu, 2 Apr 2020 03:02:37 +0000 Subject: CTAN sync 202004020302 --- info/tex-nutshell/README | 19 + info/tex-nutshell/tex-nutshell.pdf | Bin 0 -> 231384 bytes info/tex-nutshell/tex-nutshell.tex | 2182 ++++++++++++++++++++++++++++++++++++ 3 files changed, 2201 insertions(+) create mode 100644 info/tex-nutshell/README create mode 100644 info/tex-nutshell/tex-nutshell.pdf create mode 100644 info/tex-nutshell/tex-nutshell.tex (limited to 'info') diff --git a/info/tex-nutshell/README b/info/tex-nutshell/README new file mode 100644 index 0000000000..5979f30d6c --- /dev/null +++ b/info/tex-nutshell/README @@ -0,0 +1,19 @@ + +Document: TeX in a nutshell + +Author: Petr Olsak, + Czech Technical University in Prague + +This software is in public domain. + +The pure TeX features are described here. +The main goal of this document is its brevity. +I hope that this document can be useful for somebody +who is looking for information about basics of TeX. + +Files: +tex-nutshell.tex ... source file +tex-nutshell.pdf ... the document + +Version: +See the end of the document. diff --git a/info/tex-nutshell/tex-nutshell.pdf b/info/tex-nutshell/tex-nutshell.pdf new file mode 100644 index 0000000000..43af9c3cf5 Binary files /dev/null and b/info/tex-nutshell/tex-nutshell.pdf differ diff --git a/info/tex-nutshell/tex-nutshell.tex b/info/tex-nutshell/tex-nutshell.tex new file mode 100644 index 0000000000..7ea0acc537 --- /dev/null +++ b/info/tex-nutshell/tex-nutshell.tex @@ -0,0 +1,2182 @@ +\useoptex % We are using OpTeX, no LaTeX + +\report +\fontfam[pagella] + +\emergencystretch=2em +\hbadness=2100 +\catcode`<=13 +\def<#1>{{\def\ { }\iindex{:#1}\iis {:#1} {$\langle\hbox{\it#1}\rangle$}}% + $\def\,{\hskip1.5pt plus.3pt minus1.2pt}\,\langle\hbox{\it#1}\rangle\,$} +\everyintt={\catcode`<=13 \Blue} +\onlyrgb +\addto\_titfont\Blue +\def\Green{\setrgbcolor{0 .8 0}} + +\def\myunderline#1{\vtop{\hbox{#1}\kern-\prevdepth \kern2pt \hrule}} +\adef/#1.{\myunderline{#1}} +\adef|#1;{{\Red#1}} +\toksapp\everyintt{\catcode`\/=13 \catcode`\|=13} +\catcode`\/=12 \catcode`\|=12 +\adef\%#1\par{{\adef\%{\%}\Green\%#1}\par} +\catcode`\%=14 +\toksapp\everytt{\catcode`\%=13} + +\def\*{*} +\def\c#1{$_{#1}$} + +\activettchar` +\enquotes + +% to index macros: +\def\i #1 {\ii .#1 \iis .#1 {{\code{\\#1}}}} +\def\x`{\bgroup\_setverb\xx} +\bgroup \lccode\string`\.=\string`\` \lowercase{\egroup \def\xx #1#2.{\i #2 \egroup `#1#2.}} +\def\y`{\bgroup\_setverb\yy} +\def\yy #1#2={\i #2 \egroup `#1#2=} + +% Hyperlinks +\hyperlinks\Red\Green +\fnotelinks\Magenta\Magenta + + + +\tit \TeX/ in a nutshell + +\author Petr Olšák + +The pure \TeX/ features are described here, no features provided by +macro extensions. Only the last section gives a summary of plain \TeX/ +macros. + +The main goal of this document is its brevity. So features are described +only roughly and sometimes inaccurately here. If you need to know more then you can read +free available books, for example +\ulink[https://eijkhout.net/texbytopic/texbytopic.html]{\TeX/ by topic} +or +\ulink[http://petr.olsak.net/tbn.html]{\TeX/book naruby}. +Try to type `texdoc texbytopic` in your system. + +\ii OpTeX \ulink[http://petr.olsak.net/optex]{\OpTeX/} manual +supposes that the user knows the basics principles of \TeX/ itself. +If you are converting from \LaTeX/ to \OpTeX/ for example\fnote +{Congratulations to your decision:-)} +then you may welcome a summary +document that presents these basic principles because \LaTeX/ manuals +typically don't distinguish between \TeX/ features and features specially +implemented by \LaTeX/ macros. + +\notoc\nonum\sec Table of contents + +\maketoc \outlines0 + + +\sec[termi] Terminology + +The main principle of \TeX/ is that its input files can be a mix +of the material which could be printed and \ii control~sequence {\em control sequences} +which gives a setting for build-in algorithms of \TeX/ or gives a special message +to \TeX/ what to do with the inputted material. + +Each control sequence (typically a word prefixed by a backslash) has its +\ii meaning~of~control~sequence {\em meaning}. +There are four types of meanings of control sequences: + +\begitems +* the control sequence can be a \ii register {\em register}, it means it represents a variable which + is able to keep a value. There are \ii primitive/register {\em primitive registers}. Their values influence + behavior of build-in algorithm (e.g. \i hsize `\hsize`, \i parindent `\parindent`, + \i hyphenpenalty `\hyphenpenalty`). On the other hand \ii decalared/register {\em declared registers} + are used by macros (e.g. \i medskipamount `\medskipamount` used in plain \TeX/ + or \i ttindent `\ttindent` + used by \ii OpTeX \OpTeX/). +* the control sequence can be a \ii primitive/command {\em primitive command}, it runs a build-in + algorithm (e.g. \i def `\def` declares a macro, \i halign `\halign` runs algorithm for + tables, \i hbox `\hbox` creates a box in typesetting output). +* the control sequences can be a \ii character/constant {\em character constant} + (declared by \i chardef `\chardef` + or \i mathchardef `\mathchardef` primitive command) or a font selector (declared + by \i font `\font` primitive command). +* the control sequence can be a \ii macro {\em macro}. When it is read then it is + replaced by its \ii replacement/text {\em replacement text} in the input queue. If there are more + macros in the replacement text, all macros are replaced too. It is so called + \ii expansion/process {\em expansion process} which ends on the level of text to be printed or + primitive commands or registers or character constants or font selectors. +\enditems + +Example. When \TeX/ reads: +\begtt +\def\TeX{T\kern-.1667em\lower.5ex\hbox{E}\kern-.125emX} +\endtt +in a macro file then the `\def` primitive command saves the information that +\i TeX `\TeX` is a control sequence with meaning \"macro", the replacement text is +declared here and it is a mix of a material to be typeset: `T`, `E` and `X` +and primitive commands +\i kern `\kern`, \i lower `\lower`, \i hbox `\hbox` +with their parameters in given syntax. Each +primitive command has declared syntax, for example, `\kern` must be followed +by dimension specification in the format \"decimal number followed by a unit". +More about this primitive syntax is in the sections~\ref[reg], \ref[expand] and~\ref[main]. + +When a control sequence `\TeX` with meaning \"macro" occurs in the +input stream then it is \ii expansion {\em expanded} to its replacement text, i.e the sequence of +typesetting material and primitive commands in our case of `\TeX` macro. +The logo \TeX/ is printed as a result of this processing. + +None of the control sequences have their definitive meaning. The control sequence +could change its meaning by re-defining it as a new macro (using `\def`), +redeclaring it as an arbitrary object in \TeX/ (using \i let `\let`) etc. +When you re-define a primitive control sequence then the access to its value +or build-in algorithm is lost. This is a reason why \ii OpTeX \OpTeX/ macros duplicate +all primitive sequences (\i hbox `\hbox` and `\_hbox`) with the same meaning and use +only \"private" control sequences (prefixed by `_`. So, user can re-define +`\hbox` without the loss of the primitive command `\_hbox`. + +\sec Formats, engines + +\TeX/ is able to start without any macros preloaded in so-called \ii ini-TeX/state {\em ini-\TeX/ +state} (the `-ini` option on the command line must be used). It knows only Cca 300 +primitive registers and primitive commands at this state.\fnote +{Roughly speaking, if you know all these 300 primitive objects and all syntax +of primitive commands and all build-in algorithms then you know all about \TeX. +But starting to produce common documents from this primitive level without +macro support is nearly impossible.} +When ini-\TeX/ reads macro files then new control sequences are +declared as macros, declared registers, character constants or font +selectors. The primitive command \i dump `\dump` saves the binary image of the \TeX/ memory +(with newly declared control sequences) to the \ii format,format/file {\em format file} (`.fmt` +extension). + +The original intention of existence format files was to prepare a +collection of macro declarations, register settings and to load default fonts and +to dump this information to a file for later use. Such collection typically +declares macros for the markup of documents and for typesetting design. This is +the reason why we call these files {\em format files}: they give a format +of documents on the output side and declares markup rules for document source files. + +When \TeX/ is started without `-ini` option then it tries to load a prepared +format file into its memory and to continue with reading more macros or a real +document (or both). The starting point is at the place where \i dump `\dump` was +processed during ini-\TeX/ state. If the format file is not specified +explicitly (by `-fmt` option on the command line) then \TeX/ tries to read the +format file with the same name which is used for running \TeX. For example +`tex document` runs \TeX, it loads the format `tex.fmt` and reads the +`document.tex`. Or `latex document` runs \TeX, it loads the format `latex.fmt` +and reads the `document.tex`. + +The `tex.fmt` is format file dumped when \ii plain~TeX/macros {\em plain \TeX/ macros}\fnote +{Plain \TeX/ macros were made by \ii Knuth/Donald Donald Knuth, the author of \TeX. It is a +set of basic macros and settings which is used (more or less) as a subset of +all other macro packages.} +were read and `latex.fmt` is format file dumped when \ii LaTeX/macros {\em \LaTeX/ macros} were read. +This is typically done when a \TeX/ distribution is installed without any user +intervention. So, the user can run `tex document` or `latex document` without +worry that these typical format files exist. + +From this point of view, \LaTeX/ is nothing more than a format of \TeX/, +i.e.~a collection of macro declarations and register settings. + +A typical \TeX/ distributions have four common \ii TeX/engines {\em \TeX/ engines}, i.e.~programs +they implement classical \TeX/ algorithms with various extensions: + +\begitems +* \TeX/ -- only classical \TeX/ algorithms by Donald Knuth, +* \ii pdfTeX pdf\TeX -- an extension supporting PDF output directly and + micro-typographical features, +* \ii XeTeX Xe\TeX/ -- an extension supporting Unicode and PDF output, +* \ii luaTeX lua\TeX/ -- an extension supporting Lua programming, Unicode, + micro-typographical features and PDF output. +\enditems + +Each of them are able to run in ini-\TeX/ state or with a format file. For +example the command `luatex -ini macros.ini` starts lua\TeX/ at ini-\TeX/ state, +read `macros.ini` file and final `\dump` command is supposed here to create +a format `macros.fmt`. Then user can use the command `luatex -fmt macros document` to +load `macros.fmt` and to process the `document.tex`. +Or the command `luatex document` processes lua\TeX/ with `document.tex` and +with `luatex.fmt` which is a little extension of plain \TeX/ macros. Another example: +`lualatex document` runs lua\TeX/ with `lualatex.fmt`. It is a format with +\LaTeX/ macros for lua\TeX/ engine. Final example: +`optex document` runs Lua\TeX/ with `optex.fmt` which is +a format with \ii OpTeX \ulink[http://petr.olsak.net/optex]{\OpTeX/ macros}. + +\sec Searching data + +If \TeX/ needs to read something from the file system (for example the +primitive command \i input `\input` or +\i font `\font=` is used) +then the rule +\"first wins" is applied. \TeX/ looks at the current directory first or +somewhere to the \TeX/ installation second. The behavior in the second step +depends on the used \TeX/ distribution. For example +\ii TeXlive \ulink[https://www.tug.org/texlive]{\TeX/live} programs are +linked with a \ii kpathsea {\em kpathsea} library and they do the following: Search the given +file in the current directory, then in \ii texmf~tree \code{~/texmf} tree (data are saved by +the user here), then in `texmf-local` tree (data are saved by the system administrator +here, they are not removed when \TeX/ distribution is upgraded), +then in `texmf-var` tree (data are saved automatically by programs from +\TeX/ distribution here) and then in `texmf-dist` tree (data from \TeX live +distribution). Each directory tree can be divided into sub-trees: first level +`tex`, `fonts`, `doc` etc., second level is divided by \TeX/ engines or font types etc., +more levels are typically organized to keep a clarity. +New files in the current directory on in \code{~/texmf} tree are found without +doing something more, but new files in other places have to be registered by `texhash` +program (\TeX/ distribution does automatically this during its installation). + + +\sec Processing the input + +The lines from input files are transformed by the \ii tokenizer {\em tokenizer} first. +It reads input lines and generates a sequence of tokens. The main goals of +tokenizer is + +\begitems +* It converts each control sequence to a single token characterized by its name. +* Another input material is tokenized as \"one token per character". +* The continuous sequence of more spaces is transformed into one space token. +* The end of the line is transfromed into space token, so the paragraph text + can continue in a next input line and one space token is between the last word + on the previous line and the first word on the next line. +* Comment character `%` is ignored and all the text after it to the end of line + is ignored too. +* Spaces from the begining of each line are ignored. Thus, you can + use arbitrary indentation in your source file without change of the result. +* Each empty line (or line with only spaces) is transformed to the token + \i par `\par`. This token has primitive meaning: \"finalize the current paragraph". + This implies the general rule in \TeX/ source files: paragraphs are terminated + by empty lines. +\enditems + +The behavior of the tokenizer is not definitive. Tokenizer works with a table of +category codes. Any change of category codes of characters +(done by \i catcode {\let\,=\relax`\catcode`\code{`}`\=`} +primitive command) influences tokenizer processing. For +example, the verbatim environment is declared using setting all characters to +normal meaning. + +By default, there are the following characters with special meaning. Tokenizer +converts them or sets them as special tokens used in syntactical rules in +\TeX/ later. The corresponding category codes are mentioned here as an index of the +character. + +\begitems +* `\`\c0\quad -- starts completion of a control sequence by the tokenizer. +* `{`\c1 and `}`\c2\quad -- opens and close group or have special syntactical meaning. + The main syntactical rule is: each subsequence of tokens treated by macros + or primitive commands must have these pairs o tokens balanced. There is no + exception. Tokenizer treats them as special tokens with meaning + \"opening character" and \"closing character". +* `%`\c{14}\quad -- comment character, removed by the tokenizer. +* `$`\c3, `&`\c4, `#`\c6, `^`\c7, `_`\c8, `~`\c{13}\quad -- + tokenizer treats them as a special tokens with meaning: + \ii math/mode/selector \"math-mode selector\c3", + \ii table/separator \"table separator\c4", \ii parameter/prefix \"parameter prefix for + macros\c6", \ii superscript/prefix \"superscript prefix in math\c7", + \ii subscript prefix \"subscript prefix in math\c8" + \ii active/character \"active character\c{13}" + (the active character `~` is defined as no-breakable space in all typical formats). +* Letters and other characters are tokenized as \"letter character\c{11}" or + \"other character\c{12}". +\enditems + +If you need to print these special characters you can use +\ii -percent,-at,-dollar,-hash +`\%`, `\&`, `\$`, `\#` or `\_`. These five control sequences are declared as +\"print this character" in all typical \TeX/ formats. +Another possibility is to use a verbatim environment (it depends on used format) +Last alternative: you can use \i csstring {\let\,=\relax`\csstring\`} +in lua\TeX/, because lua\TeX/ disposes +with the primitive command `\csstring` which converts `\` +to ``\c{12}. + +The \ii active~character \"active character\c{13}" +can be declared by \i catcode `\catcode`\code{`}`\=13`. +Such `` behaves like ``. For example, you can +define it by +\i def `\def{...}`. +If a `` is +listed in this document, the active character is meant too. +{\emergencystretch=2em\par} + +Each control sequence is built by the tokenizer starting from `\`\c0. Its name is +a continuous sequence of letters\c{11} finalized by first non-letter. +Note that \OpTeX/ sets +`_` as letter\c{11}, thus control sequence names can include this character. +\LaTeX/ sets the `@` as letter\c{12} when reading styles and macro files. +You can look to such files and you will see many such characters inside +private control sequence names declared by \LaTeX/ macros. + +If the first character after `\`\c0 is not letter\c{\ne11} then control sequence is +finalized with only this character in its name. So called +\ii one~character/control~sequence {\em one-character control sequence} is created. Other control sequences +are \ii multiletter/control~sequence {\em multiletter control sequences}. + +Spaces {\char9251}\c{10} after multi-letter control sequences are ignored, so the space can be used +as a terminating character of the control sequence. Another characters used +immediately after a control sequences are not ignored. So `\TeX !` and +`\TeX!` gives the same result: the control sequence `\TeX` followed +immediately by `!`\c{12}. + +Tokenizer's output (a sequence of tokens) goes to \ii expand/processor {\em expand processor} +and its output goes to \ii main/processor {\em main processor} of \TeX. The expand processor +performs expansions of macros or a primitive command which is working at expand +processor level. See a summary of such commands in the section~\ref[expand]. + +Main processor performs assignment of registers, declares macros by \i def `\def` +primitive command and runs all primitive commands at the main processor level. +Moreover, it creates the typesetting output as described in the next +section. + +The very important difference between \TeX/ and other programs is that there are no +strings, only sequences of tokens. We can return to the example +`\def\TeX{...}` above in the section~\ref[termi]. +The token \i def `\def` is a control sequence with meaning \"declare a macro". +It gets the following token \i TeX `\TeX` and +declares it as a macro with replacement text, which is the sequence of tokens: + +\medskip +\bgroup \def\b#1{\kern1pt\lower2ex\llap{\c{#1}\kern-1.5pt}} + \def`#1`#2,{\frame{\strut\tt\Blue\string#1}\b{#2}}\catcode`\{=12 \catcode`\}=12 \indent +`T`11, `\kern`, `-`12, `.`12, `1`12, `6`12, `6`12, `7`12, `e`11, `m`11, +`\lower`, `.`12, `5`12, `e`11, `x`11, `\hbox`, `{`1, `E`11, `}`2, +`\kern`, `-`12, `.`12, `1`12, `2`12, `5`12, `e`11, `m`11, `X`11, +\egroup +\medskip + +If you are thinking like \TeX/ then you must forget the term \"string" +because all texts in \TeX/ are preprocessed by the tokenizer when input lines are +read and only sequences of tokens are manipulated inside \TeX/. + +Tokenizer converts two `^`\c7`^`\c7 characters followed by ASCII uppercase +letter to the Ctrl-letter ASCII code. For example `^^M` is Ctrl-M (carriage +return). It converts two `^`\c7`^`\c7 followed by two hexadecimal digits +(`0123456789abcdef`) to one-byte code, for example, `^^0d` is Ctrl-M too +because it has code 13. Moreover, tokenizer of \XeTeX/ or lua\TeX/ converts +`^`\c7`^`\c7`^`\c7`^`\c7 followed by four hexadecimal digits or +`^`\c7`^`\c7`^`\c7`^`\c7`^`\c7`^`\c7 followed by six hexadecimal digits to one +character with given Unicode. + + +\sec Vertical and horizontal modes + +When the main processor creates the typesetting output then it alternates +between vertical and horizontal mode. It starts in \ii vertical/mode,@ {\em vertical mode}: all +materials are put vertically below in this mode. For example +\i hbox `\hbox{a}\hbox{b}\hbox{c}` creates c below b and b below a in vertical mode. + +If there is something incompatible with vertical mode principle: a special +command working only in horizontal mode or a character itself +then main processor switches to \ii horizontal/mode,@ {\em horizontal mode}: it opens +an unlimited horizontal data line for +typesetting material and puts material next to each other. For example +\i hbox `\hbox{a}\hbox{b}\hbox{c}` creates abc in horizontal mode. + +When an empty line is scanned then tokenizer creates \i par `\par` token here and +if the main processor is in horizontal mode, the `\par` command finalizes the +paragraph. More exactly it returns to the vertical mode, +it breaks the horizontal data line filled in previous horizontal mode +to parts with the \i hsize `\hsize` width. These parts are completed as +\ii box {\em boxes} and they are put one below second in the vertical mode. So, a +paragraph of \i hsize `\hsize` width is created. + +Repeatedly: if there is something incompatible with current vertical mode +(typically a character), then the horizontal mode is opened and all characters +(and spaces between them) are put to the horizontal data line. When empty line +is scanned then `\par` command is started and the horizontal +data line is broken to the lines of \i hsize `\hsize` width and next paragraph +is completed. + +In the vertical mode, the material is cumulated in a vertical data column +called \ii main/vertical/list {\em main vertical list}. +If the height of this material is greater than \i vsize `\vsize` then its part with +maximal `\vsize` height is completed as a \ii page/box {\em page box} and shipped to +\ii output/routine {\em output routine}. A programmer or designer can declare a design of pages +using macros in the output routine: header, footer, pagination, +the position of the main page box etc. The output routine completes the main page +box with another material declared in the output routine and the result is +shipped out as one page of the document. The main processor continues in +the vertical mode with the rest of the unused material in the main vertical list. +Then it can switch to the horizontal mode if a character occurs etc... + +The plain \TeX/ macro \i bye `\bye` (or primitive command \i end `\end`\fnote +{\LaTeX/ format re-defines this primitive control sequence `\end` to another +meaning which follows the logic of \LaTeX/'s markup rules.}) +starts the last +`\par` command, finalizes the last paragraph (if any), completes the last page +box, puts it to the output routine, finalizes the last page in it and \TeX/ +is terminated. + +There are \ii internal/vertical/mode {\em internal vertical mode} and +\ii internal/horizontal/mode {\em internal horizontal mode}. +They are activated when the main processor is typesetting a material +inside \i vbox `\vbox{...}` or \i hbox `\hbox{...}` primitive commands. More about boxes is in +sections~\ref[boxes] and~\ref[main]. + +Understanding of switching between modes is very important for \TeX/ users. +There are primitive commands which are context dependent on the current mode. +For example, \i par `\par` primitive command (generated by an empty line) does nothing +in vertical mode but it finalizes paragraph in horizontal mode and it causes +an error in math mode. Or \i kern `\kern` primitive command creates a vertical space in +vertical mode or horizontal space in horizontal mode. + +The following primitive commands used in the vertical mode starts the +horizontal mode: the first character of the paragraph (most common +situation) or \i indent `\indent`, \i noindent `\noindent`, \i hskip `\hskip` +(and its alternatives), +\i vrule `\vrule`\fnote {The list is not fully completed, but most important commands +are mentioned here.} and plain \TeX/ macro \i leavevmode `\leavevmode`. +When the horizontal mode is opened, the indentation of the \i parindent `\parindent` width +is included. The exception is only if the horizontal mode is started by the +\i noindent `\noindent`, then the paragraph has no indentation. + +The following primitive commands used in the horizontal mode finalizes the +paragraph and returns to the vertical mode: \i par `\par`, \i vskip `\vskip` (and its +alternatives), \i hrule `\hrule`, \i end `\end` and plain \TeX/ macro \i bye `\bye`. + +\sec Groups in \TeX/ + +Each assignment to registers, declaration macros or font selecting is local +in groups. When the current group ends then the assignments done inside the +group are forgotten and the values when this group was opened are restored. +The groups can be delimited by `{` and `}` pair or by \i begingroup `\begingroup` and +\i endgroup `\endgroup` primitive commands or by +\i bgroup `\bgroup` and \i egroup `\egroup` control +sequences declared by plain \TeX. +For example, plain \TeX/ declares the macros \i rm `\rm` (selects roman font), +\i bf `\bf` (selects bold font) and \i it `\it` (selects italics) and it initializes by +\i rm `\rm` font. User can write: + +\begtt +The roman font is here {\it here is italics} and the roman font continues. +\endtt +% +Not only fonts but all registers are set locally inside a group. The macro +designer can declare a special environments with font selecting and with +more special typographical parameters in groups. + +The following example is a test of understanding vertical and horizontal +modes switching. + +\begtt +{\hsize=5cm This is the first paragraph which should be formatted + to 5 cm width.} + +But it is not true... +\endtt +% +Why the example above does not create the paragraph with a 5 cm width? +The empty line \i par (`\par`) command is placed {\em after} the group is finished, so the +\i hsize `\hsize` parameter has its previous value at the time when the paragraph is +completed, no value 5\,cm. The value of \i hsize `\hsize` register\fnote +{and about twenty other registers which declare the paragraph design} +is used when the paragraph is +completed, no at the beginning of the paragraph. This is the reason why +macro programmers put explicitly \i par `\par` command to macros before the local +environment is finished by the end of the group. Our example should look like + +\begtt +{\hsize=5cm This is the first ... to 5 cm width.\par} +\endtt + + +\sec[boxes] Box, kern, penalty, glue + +You can look at one character, say the `y`. It is represented by three +dimensions: \ii height height (above baseline), \ii depth depth (below baseline) +and \ii width width. +Suppose that there are more characters printed in horizontal mode and +completed to a line of a paragraph. This line has its height equal to +the maximal height of characters inside it, it has the depth equal to maximal +depth of all characters inside it and it has its width. Such a sequence of +characters encapsulated to one typesetting element +with its height, depth and width is +called \ii box {\em box}. Boxes are placed next to each other (from left to +right\fnote{There is an exception for special languages.}) +in horizontal mode or one above second in vertical mode. + +The boxes can include individual characters or spaces or boxes. The boxes can +include more boxes. Paragraph lines are boxes. The page box includes paragraph +lines (boxes). The finalized page with a header, page box, pagination, +etc. is a box and it is shipped out to the PDF page. Understanding boxes is +necessary for macro programmers and designers. + +You can create an individual box by the primitive command +\i hbox `\hbox{}` +or \i vbox `\vbox{}`. The `` is completed in +internal horizontal mode and `` in internal vertical +mode. Both cases open a group, create the material in a specified +mode and closes the group, where all settings are local. + +The `` can include individual characters, boxes, +horizontal \ii glue {\em glues} or \ii kern {\em kerns}. The glue is a special term for +stretchable or shrinkable and possible breakable spaces and the kern is a +term used for fixed nonbreakable spaces. + +The `` can include boxes, vertical glues or kerns. No +individual characters. If you put an individual character in the +vertical mode (for example in the \i vbox `\vbox`) +then the horizontal mode is opened. At the end of \i vbox `\vbox`\fnote +{before the \i vbox `\vbox` group is closed} +or when \i par `\par` command is invoked, the opened paragraph is finished (with +current \i hsize `\hsize` width) and the resulting lines are vertically placed +inside the \i vbox `\vbox`. + +The completed boxes are unbreakable and they are treaded as a single object in +the surrounding printed material. + +The line boxes of the paragraph have the fixed width \i hsize `\hsize`, so there must +be something stretchable or shrinkable in order to get desired fixed width +of lines. Typically the spaces between words have this feature\fnote {When +the microtypographical +feature \i pdfadjustspacing `\pdfadjustspacing` is activated, then not +only spaces are stretchable and shrinkable but individual characters are +slightly deformed (by invisible amount) too.} These spaces have declared +their \ii default/size/of~space {\em default size}, their +\ii stretchability {\em stretchability} and their +\ii shrinkability {\em shrinkability} in the font metric data of currently used font. + +You can place such glue explicitly by the primitive command: + +\begtt \catcode`<=13 +\hsize plus minus +for example: +\hsize 10pt plus5pt minus2.5pt +\endtt +% +This example places the glue with 10\,pt default size, stretchable to +15\,pt\fnote +{It can be stretchable ad absurdum (more than 15\,pt) but with very +considerable \ii badness {\em badness} calculated by \TeX/ whenever glues are stretched +or shrank.} +and shrinkable to 7.5\,pt as its minimal size. +All glues in one line are stretched or shrank equally but with weights given +from their stretchability/shrinkability values. + +You can do experiments of this feature if you say \i hbox `\hbox to{...}`. +Then the \i hbox `\hbox` is created with a given width. Probably, the glues inside +this \i hbox `\hbox` must be stretched or shrank. You can see in the log +that the total \ii badness {\em badness} is calculated, it represents the amount of a +\"force" used to all glue included in such \i hbox `\hbox`. + +An infinitely stretchable (to an arbitrary positive value) or shrinkable +(to an arbitrary negative value) glue +can exist. This glue is stretched/shrank and other glues with +finite amounts of stretching or shrinking keep their default size in such +case. +You can put infinitely stretchable/\penalty0shrinkable +\ii glue glue using the reserved unit \ii fil `fil` +in \i hskip `\hskip` command, for example +the command \i hskip `\hskip 0pt plus 1fil` means zero default size but infinitely stretchable. +There is a shortcut for such glue: \i hfil `\hfil`. When you type +`\hbox to\hsize{\hfil \hfil}` then the `` is centered. +But if the `` is wider than \i hsize `\hsize` then \TeX/ reports an +\ii overfull/box `overfull \hbox`. If you want to center a wide `` too, you can use +\i hss `\hss` instead \i hfil `\hfil`. The \i hss `\hss` primitive command is equal to +`\hskip 0pt plus1fil minus1fil`. The `` printed by +`\hbox to\hsize{\hss\hss}` is now centered in its arbitrary size. + +A glue created with \ii fill `fill` stretchability or shrinkability (double ell) +is infinitely more stretchable or shrinkable than glues with only \ii fil `fil` unit. +So, glue with \ii fill `fill` are stretched or shrank and glues with only `fil` in +the same box keep their default size. For example, a macro declares centering +a `` by +\i hbox `\hbox to\hsize{\hss \hss}` and user can create the `` in the form +\i hfill `\hfill `. Then `` is printed flushed right because +\i hfill `\hfill` is a shortcut to \i hskip `\hskip0pt plus1fill` and has greater priority than +glues with only \ii fil `fil` unit. + +Common usage is \i hbox `\hbox to0pt{\hss}` or `\hbox to0pt{\hss}`. +The box with zero width is created and the text overlaps this dimension to +right (first example) or to left (second example). \ii plain~TeX Plain \TeX/ declares +macros for these cases: \i rlap `\rlap{}` or \i llap `\llap{}`. + +The last line of each paragraph is finalized by a glue of type \i hfil `\hfil` by +default. When you write \i hfill `\hfill ` in vertical mode (`` is +something like a table, image or whatever else in the box) then `` is +flushed right, because the paragraph is started by the `\hfill` space but +finalized only by \i hfil `\hfil` space. If you type +\i noindent `\noindent\hfil ` then +the is centered. And putting only `` places it to the left +side because the common left side is default placement rule in the vertical +mode. + +The same principles concerned with horizontal glues are applicable for vertical +modes where glues are created by \i vskip `\vskip` commands instead `\hskip`. You can +write \i vbox `\vbox to{...}` and do experiments. + +If a glue is put to the horizontal data line in horizontal mode and +paragraph breaking algorithm decides about the suitable breakpoints for creating +lines with desired width \i hsize `\hsize`, then each glue is potentially breakable +point. Each glue can be preceded by a \ii penalty {\em penalty} value (created by +\i penalty `\penalty` primitive) in the typical range +-10000 to 10000. The paragraph breaking algorithm gets a penalty if it decides +to break line in the glue with given penalty value preceded. If no penalty +is declared for a given glue, then it is the same as a penalty equal to zero. +The penalty value 10000 or more +means \"impossible to break". The negative penalty means a bonus for paragraph +breaking algorithm. The penalty -10000 or less means \"you must break here". + +The paragraph breaking algorithm tries to find an optimum of breakpoints +positions concerning all penalties, to all badnesses of all created lines and to +many more values not mentioned here in this brief document. +The analogical optimal breakpoint is found in the vertical material when \TeX/ +breaks it into pages. + +The concept \"box, penalty, glue" with the optimum-fit breaking +algorithms makes \TeX/ unique between many other typesetting software. + + +\sec Syntactical rules + +The primitive commands can get their parameters written after it. These +parameters must suit syntactical rules given for +each primitive command. Some parameters are optional. For example +\i hskip `\hskip /plus. /minus.` means that +the parameter `` must follow (it must suit syntactical rules for +dimensions, see section \ref[reg]) then the optional parameter prefixed by keyword +\ii plus `plus` can follow +and then the optional parameter prefixed by \ii minus `minus` can follow. +We denote the optional parameters by underline in this document. +{\emergencystretch=2em\par} + +The \ii keyword {\em keywords} (typically prefixes some parameters) may have optional spaces +around them. + +If the syntactical rule mentions the pair `{`, `}` then these characters are +not definitive: other characters may be tokenized with this special meaning but it +is not common. The text between this pair must be \ii balabced/text {\em balanced} with respect to this +pair. For example the syntactic rule \i message `\message{}` supposes that +`` must not be `ab{cd` but `ab{c{}}d` is allowed for instance. + +By default, all parameters read by primitive commands are got from input +stream tokenized and fully expanded by the expand processor. But +sometimes, when \TeX/ reads parameters for a primitive command, the expand +processor is deactivated. We denote these parameters by red color. For +example \i let `\let|=;` means that these parameters +processed by `\let` command are not expanded. + +Whenever a syntactical rule mentions the \ii equal/sign `=` character (see the previous example +with \i let `\let` command, then this is the equal sign tokenized as a normal character +and it is optional. The syntactical rule allows to omit it. Optional spaces +are allowed around this equal sign. + +The concept of the optional parameters of primitive commands +(terminated if something different from +the keyword follows) may bring troubles if a macro programmer +forget to terminate an uncomplete parameter text by \x`\relax` command +(`\relax` does nothing but it can terminate a list of optional parameters of +the previous command). +Suppose, for example, that `\mycoolspace` is defined +by `\def\mycoolspace{\penalty42\hskip2mm}`. If an user write +`first\mycoolspace plus second` then \TeX/ reports the error +`missing` `number,` `treated` `as` `zero` in the position of `s` character +and appends: \code{ s}. An user who is unfamiliar with +\TeX/ primitive commands and their parameters is totally lost. The correct +definition looks like: `\def\mycoolspace{\penalty42\hskip2mm\relax}`. + +\sec[def] Principles of macros + +Macros can be declared by \i def `\def` primitive command (or `\edef`, `\gdef`, +`\xdef` commands, see below). The syntax is +`\def|/.{};`. + +The `` are a sequence of formal parameters of the declared macro +written in the form `#1`, `#2`, etc. +They must be numbered from one and incremented by one. +The maximal number of declared parameters is nine. +These parameters can be used in the ``. This specifies the +place where the real parameter is positioned when the macro is expanded. For +example: + +\begtt +\def\test #1{here is "#1".} +\test A % expands to: here is "A". +\def\swap #1#2{#2#1} +\swap AB % expands to: BA +\test {param} % expands to: here is "param". +\swap A{param} % expands to: paramA +\endtt +% +Note that there are two possibilities of how to write real macro +parameters when a macro is in use. The parameter is one token by default but +if there is `{}` then the parameter is ``. The braces +here are delimiters for the real parameter. + +The example above shows a declaration of \ii unseparated/parameter,@ {\em unseparated parameters}. The +parameters were declared by `#1` or `#1#2` with no text appended to such +declaration. But there is another possibility. +Each formal parameter can have a text appended in its declaration, so +the general syntax of declaration of formal parameters is +`#1/.#2/.;` etc. If such `` is appended then we say that +the parameter is \ii separated/parameter,@ {\em separated} or +\ii delimited/parameter,@ {\em delimited} by text. +The same delimiter must be used when the macro is in use. For example + +\begtt +\def\Test #1#2..#3 {first "#1", second "#2", third "#3".} +\Test ABC..DEF G % expands to: first "A", second "BC", third "DEF". + % the letter G follows after expansion. +\endtt +% +In the example above the `#1` parameter is unseparated (one token is read as +a real parameter if not used the syntax `{}`). The `#2` parameter +is delimited by two dots and the `#3` parameter is delimited by space. + +There should be a `` immediately before `#1` in the parameter +declaration. This means that the declared macro must be used with the same +immediately appended. If not, \TeX/ reports the error. +General rule for declaration a macro with three parameters should be: +\i def +`\def|/.#1/.#2/.#3/.{};`. + +The rule \"everything must be balanced" is applied to separated parameters +too. It means that `\Test AB{C..DEF G}.. H` from the example above reads +`B{C..DEF G}` to the `#2` parameter and the `#3` parameter is empty +because the space (the delimiter of `#3` parameter) immediately follows two dots. + +The separated parameter could bring a potential problem when the user forgot the +delimiter or the delimiter is specified incorrectly. Then \TeX/ reports the +error. This error is reported when the first \i par `\par` is scanned to the +parameter (probably generated from an empty line). If you really want to scan +to the parameter more paragraphs including `\par` between them then you can +use \i long `\long` prefix before `\def`. For example `\long\def\scan#1\stop{...}` +reads the parameter of the `\scan` macro to the `\stop` control sequence +and this parameter could include more paragraphs. +If the delimiter is missing when \i long `\long` defined macro is processed then +\TeX/ reports the error at the end of the file. + +When a real parameter of a macro is scanned then the expand processor is deactivated. +When the `` is processed then the expand processor works +normally. It means that if parameters are used in `` then +they are expanded here. + +If a macro declaration is used inside `` of another macro +then the number of `#` must be doubled for inner declaration. Example: + +\begtt +\def\defmacro#1#2{% + \def#1##1 ##2 {##1 says: #1 ##2.}% +} +\defmacro \hello {hello} % expands to \def\hello#1 #2 {#1 says: hello #2.} +\defmacro \goobye {good bye} +\hello Jane Eric % expands to: Jane says: hello Eric. +\goodbye Eric John % expands to: Eric says: good bye John. +\endtt + +Note the `%` characters used in the `\defmacro` definition. They mask +the end of lines. If you don't use them then the space tokens are here (generated +by tokenizer at the end of each line). The `` of `\defmacro` will be +`\def#1...{...}` in such case. Each usage of `\defmacro` +generates two unwanted spaces. It is not a problem if `\defmacro` is used in +the vertical mode because spaces are ignored in this mode. But +if `\defmacro` is used in horizontal mode then +these spaces are printed\fnote +{More precisely, they are transformed into horizontal glues used between words.}. + +The macro declaration behaves as another assignment, so the information about +such declaration is lost if it is used in a group and the group is left. +But you can use \i global `\global` prefix before \i def `\def` or the primitive +\i gdef `\gdef`. Then the assignment is global regardless of groups. + +When `\def` or `\gdef` is processed then `` is read with +deactivated expand processor. We have alternatives \i edef `\edef` (expanded def) +and \i xdef `\xdef` (global expanded def) which read their `` +expanded by expand processor. The summary of `\def` syntax is: + +\begtt \catcode`\|=13 \catcode`\/=13 \catcode`\<=13 \Blue +\def|/.{}; % local assignment +\gdef|/.{}; % global assignment +\edef|/.{;} % local assignment +\xdef|/.{;} % global assignment +\endtt + +You can set \i tracingmacros `\tracingmacros=2` and you can see to log file how the macros are expanded. + +\sec Math modes + +The `$`\c3`$`\c3 specifies a math formula inside the line of the +paragraph. It processes the `` in a group and in +\ii internal/math/mode,math/mode/internal {\em internal math mode}. +The `$`\c3`$`\c3`$`\c3`$`\c3 generates a separate line with math +formula(s). It processes the `` in a group and in +\ii display/math/mode,math/mode/display {\em dislay math mode}. + +The fonts in math mode are selected by very specific manner which is independent +on current text font. Six different math object are automatically detected +in math mode: \x`\mathord` (normal material), \x`\mathop` (big operators), +\x`\mathbin` (binary operators), \x`\mathrel` (relations), \x`\mathopen` (open +brackets), \x`\mathclose` (close brackets), \x`\mathpunct` (punctuations). They +can be processed in four styles \x`\displaystyle` (default in the display mode), +\x`\textstyle` (default in the internal math mode), \x`\scriptstyle` (used for +indexes or exponents, more small text) and \x`\scriptscriptstyle` +(used in indexes of indexes, smaller text). + +The math algorithms were implemented to \TeX/ by its author with very care. +All typographical traditions of math typesetting were taken into account. +There are three chapters about math typesetting in his \TeX/book. Moreover, +there is the detailed appendix G with exact specification of generating math +formulas here. This topic is unfortunately out of the frame of this short +text. + +There is a good a piece of news: all formats (including \LaTeX/) take default \TeX/ +syntax for ``. So, \LaTeX/ manuals or \LaTeX/ documents +serves a good source if you want to get to know the rules of math typesetting +by \TeX. There is only one significant difference. Fractions are constructed at +the primitive level by the \x`\over` primitive: +`{\over}` but \LaTeX/ uses a macro \x`\frac` in the +syntax `\frac{}{}`. Plain \TeX/ users (including the +author of \TeX/) prefer the syntax which follows the +principle \"how a human reads the formula". On the other hand, the +\x`\frac` syntax is derived from machine languages. You can define the +\x`\frac` macro by `\def\frac#1#2{{#1\over#2}}` if you want. + + +\sec[reg] Registers + +\ii register There are four types of registers used in \TeX: + +\begitems \def\!{\kern-1pt} +* \ii counter/type/register {\em Counters}, their values are integer numbers. Counters are declared by + \i newcount `\newcount|;`\fnote + {The declarators \x`\newcount`, \x`\newdimen`, \x`\newskip` and \x`\newtoks` + are plain \TeX/ macros used in all known \TeX/ formats. They provides + `
` allocation and uses the + `\count
`\!, `\dimen
`\!, `\skip
` and `\toks
` + \TeX/ registers. The \x`\countdef`, \x`\dimendef`, \x`\skipdef` and \x`\toksdef` + primitive commands are used internally.} + or they are primitive registers (\x`\linepenalty` for example). + \TeX/ interprets primitive commands which represent an integer from + an internal table as counter type register too + (examples: \x`\catcode`\code{`A}, \x`\lccode`\code{`A}). +* \ii dimen/type/register {\em Dimen type}, their values are dimensions. They are declared by + \i newdimen `\newdimen|;` or they are primitive registers (\x`\hsize`, for example). + \TeX/ interprets primitive commands which represent a dimension + value as dimen type register too (example: \i wd `\wd0`). +* \ii glue/type/register {\em Glue type}, their values are triples like in general + \x`\hskip` parameters. + They can be declared by \i newskip `\newskip|;` or they are primitive + registers (\x`\abovedisplayskip` for example).\fnote + {Very similar {muglue type} for math glues exists too + but it is not described in this text.} +* \ii token/type/register {\em Tokens lists}, their values are sequences of tokens. They are + declared by \i newtoks `\newtoks|;` or they are primitive registers + (\x`\everypar` for example). +\enditems + +The following example shows, how registers are declared, how the value is +saved to the register and how to print the value of the register. + +\tmpnum=42 \tmpdim=-13cm \skip0=10mm plus 12mm minus1fil \toks0={abCd ef} +\begtt +\newcount \mynumber +\newdimen \mydimension +\newskip \myskip +\newtoks \mytoks +\mynumber = 42 +\mydimension = -13cm +\myskip = 10mm plus 12mm minus1fil +\mytoks = {abCd ef} +To print these vaules use the primitive command "the": +\the\mynumber, \the\mydimension, \the\myskip, \the\mytoks. +\bye +\endtt +% +This example prints: To print these values use the primitive command "the": +\the\tmpnum, \the\tmpdim, \the\skip0, \the\toks0. Note that the human +readable dimensions are converted to typographical points~(pt). + +The general syntactic rule for storing values to registers is +`=` where the equal sign is optional and it can be surrounded by +optional spaces. Syntactic rules for each type of `` depending on +type of the register (i.\,e.\ ``, ``, `` and ``) follows. + +\begitems \let\_aboveliskip=\relax +* The `` could be +\begitems \style - +* a register of counter type; +* a character constant declared by \x`\chardef` or \x`\mathchardef` primitive command. +* an integer decimal number (with optional `+` or `-` prefixed) +* {\let\,=\relax `"`} where `` can include digits + `0123456789ABCDEF`\,; +* {\let\,=\relax`'`} where `` can include digits + `01234567`\,; +* {\let\,=\relax \code{`}``} (the prefix is the reverse single quote \code{`}). + It returns the code of the ``. Examples: + \code{`}`A` or one-character control sequence \code{`\\A}). + Both examples represent the number 65. Unicode of the character + are taken here if lua\TeX/ or Xe\TeX/ are used; +* \i numexpr `\numexpr`.\fnote + {This is a feature of e\TeX/ extension. It is implemented in pdf\TeX, Xe\TeX/ and lua\TeX.} + The `` uses operators `+`, `-`, `*` and \code{/} and + brackets `(`, `)` in normal sense. The operands are ``s. It + is terminated by something incompatible with + the syntactic rule of `` or by `\relax`. + If the result is non-integer, then it is rounded (no truncated). +\enditems +* The `` could be +\begitems \style - +* a register of dimen type or counter type; +* a decimal number with an optional decimal point (and optional `+` or `-` + prefixed) followed by ``. The `` is \ii pt `pt` (point)\fnote + {1\,pt = 1/72.27\,in $\doteq$ 0.35\,mm\,;\ 1\,pc = 12\,pt\,;\ + 1\,bp = 1/72\,in\,;\ 1\,dd $\doteq$ 1.07\,pt\,;\ 1\,cc = 12\,dd\,;\ + 1\,sp = $2^{-16}$\,pt = \TeX/ accuracy.} + or \ii mm `mm` or \ii cm `cm` or \ii in `in` or + \ii bp `bp` (big point) or \ii dd `dd` (Didot point) or \ii pc `pc` (pica) or + \ii cc `cc` (cicero) or \ii sp `sp` or \ii em `em` (quad of current font) or + \ii ex `ex` (ex~height of current font) or a register of dimen type; +* \i dimexpr `\dimexpr`. + The `` uses operators `+`, `-`, `*` and \code{/} and + brackets `(`, `)` in normal sense. The operands of `+` and `-` are + ``s, the operators of `*` or \code{/} are the pair `` and + `` (in this order). The `` + is terminated by something what is incompatible with + syntactic rule of `` or by `\relax`. +\enditems +* The `` could be: +\begitems \style - +* a register of glue type or dimen type or counter type; +* `/plus. /minus.`. The + `` is the same as ``, but normal `` + or pseudo-unit `fil` or `fill` or `filll` can be used. +\enditems +* The `` could be +\begitems \style - +* `/.{|};`. The `` is typically a sequence of + `\expandafter` primitive commands (zero or more). The `` is + scanned without expansion but the exception can be given by + ``. +\enditems +\enditems + +\removelastskip +The main processor reads input tokens (from the output of activated or +deactivated expand processor) in two contexts: +\ii do/something/context,context/do/something {\em do something} or {\em +read parameters}. By default it is in the context {\em do something}. When a +primitive which allows a parameters is read, main processor reads the +parameters in the context \ii read/parameters/context,context/read/parameters {\em read parameters}. + +Whenever the main processor reads a register in the context +{\em do something} it assumes that an assignment of a value to the register +is declared here. The following text (equal sign and ``) is read in the context +{\em read parameters}. If the following text isn't +compliant to the appropriate syntactic rule, \TeX/ reports an error. + +Examples of register manipulations: + +\begtt +\newcount\mynumber \newdimen\mydimension \newdimen\myskip +\hsize = .7\hsize % see the rule for , unit could be a register +\hoffset = \dimexpr 10mm - (\parindent + 1in) \relax % usage of \dimexpr +\myskip = 10pt plus15pt minus 3pt +\mydimen = \myskip % the information "plus15pt minus 3pt" is lost +\mynumber = \mydimen % \mynumber = 10*2^16 because \mydimen = 10*2^16 sp +\endtt +% +Each dimension is saved internally as an integer multiple of `sp` unit in +\TeX. When we need a conversion `` $\to$ ``, then simply the +internal unit `sp` is omitted. + +The summary of most commonly used primitive registers including their default +value given by plain \TeX/ follows. + +\begitems \rightskip=0pt plus1fil +* \y`\hsize=6.5in`, + \y`\vsize=8.9in` + are paragraph width and page height. + +* \y`\hoffset=0pt`, + \y`\voffset=0pt` give left margin and top margin of the page. They are + calculated from \ii page/origin {\em page origin} which is defined by coordinates + \y`\pdfvorigin=1in` and \y`\pdfhorigin=1in` measured from left upper corner of + the page. + +* \y`\parindent=20pt` is the indentation of the first line of each paragraph. + +* \y`\parfillskip=0pt plus 1fil` is horizontal glue added to the last line of the + paragraph. + +* \y`\leftskip=0pt`, \y`\rightskip=0pt`. Glues added to each line in the + paragraph from the left and the right side. If the stretchability is decared here, + then the paragraph is ragged left/right. + +* \y`\parskip=0pt plus 1pt` is vertical space between paragraphs. + +* \y`\baselineskip=12pt`, + \y`\lineskiplimit=0pt`, + \y`\lineskip=1pt`. + \ii baselineskiprule The {\em `\baselineskip` rule} says: + Two consecutive lines in vertical list have baseline distance given + by \x`\baselineskip` by default. The appropriate real glue is inserted + between the lines. + But if this real glue (between boxes) is less than \x`\lineskiplimit` + then only \x`\lineskip` between boxes is inserted. + +* \y`\topskip=10pt` is the distance between top of page box and the baseline of + the first line. + +* \y`\linepenalty=10`, + \y`\hyphenpenalty=50`, + \y`\exhyphenpenalty=50`, + \y`\binoppenalty=700`, + \y`\relpenalty=500`, + \y`\clubpenalty=150`, + \y`\widowpenalty=150`, + \y`\displaywidowpenalty=50`, + \y`\brokenpenalty=100`, + \y`\predisplaypenalty=10000`, + \y`\postdisplaypenalty=0`, + \y`\interlinepenalty=0`, + \y`\floatingpenalty=0`, + \y`\outputpenalty=0`. + These penalties are put to various places in the vertical or horizontal + list. Most important are \x`\clubpenalty` (below the first line of a paragraph) + and \x`\widowpenalty` (before last line of paragraph). Typographical rules + give us to set these register to 10000 (no page break is allowed here). + +* \y`\looseness=0` allows to create a \"suboptimal" paragraph. The page-building + algorithm tries to builds the paragraph with \x`\loosenes` lines more than + the optimal solution. If the \x`\tolerance` has not sufficiently large value + then this setting is simply ignored. It is reset to zero after each + paragraph is completed. + +* \y`\spaceskip=0pt`, + \y`\xspaceskip=0pt`. If non-negative they are used as glues between words. + Default values are read from the font metric data of the current font. + +* \y`\pretolerance=100`, + \y`\tolerance=200`, \y`\emergencystretch=0pt` + \y`\doublehyphendemerits=10000`, + \y`\finalhyphendemerits=5000`, + \y`\adjdemerits=10000`, + \y`\hfuzz=0.1pt`, + \y`\vfuzz=0.1pt` +are parameters for paragraph building algorithm not described here in +detail. + +* \y`\hbadness=1000`, + \y`\vbadness=1000`. \TeX/ reports a warning about \iid badness on the terminal + and to the log file if it is greater than these values. The warning has the form + \ii underfull/box `underfull` `\hbox` or `underfull \vbox`. The value `100` + means that the `plus` limit for glues is reached. + +* \y`\tracingonline=0`, + \y`\tracingmacros=0`, + \y`\tracingstats=0`, + \y`\tracingparagraphs=0`, + \y`\tracingpages=0`, + \y`\tracingoutput=0`, + \y`\tracinglostchars=1`, + \y`\tracingcommands=0`, + \y`\tracingrestores=0`, + \y`\tracingscantokens=0`, + \y`\tracingifs=0`, + \y`\tracinggroups=0`, + \y`\tracingassigns=0`. + If these registers have positive values then \TeX/ reports details about + the processing of build-in + algorithms to the log file. If \i tracingonline `\tracingonline>0` then the same + output is on the terminal. + +* \y`\showboxbreadth=5`, + \y`\showboxdepth=3`, + \y`\errorcontextlines=5`. + The amount of information when boxes are traced to the log file or an error is + reported. + +* \y`\language=0`. + \TeX/ is able to load more hyphenation patters for more + languages. This register points to the index of currently used + hyphenation patterns. Zero means English. + +* \y`\lefthyphenmin=2`, \y`\righthyphenmin=3`. Maximal letters left or right of + hyphenated words. + +* \y`\defaulthyphenchar=`\code{`}`\-`. This character is used when words are + hyphenated. + +* \y`\globaldefs=0`. If it is positive then all settings are global. + +* \y`\hangafter=1`, + \y`\hangindent=0pt`. + If \x`\hangindent` is positive, then after \x`\hangafter` lines all following + lines are indented. Negative/positive values of \x`\hangindent` or \x`\hangafter` does + indentation from left or right and from the top or bottom of the paragraph. + The \x`\hangindet` is set to 0 after each paragraph. + +* \y`\mag=1000`. Magnification factor of all used dimensions. + The value 1000 means 1:1. + +* \y`\escapechar=`\code{`}`\\` + use this character in the `\string` primitive. + +* \y`\newlinechar=-1`. If positive, this character is interpreted as the end of + the line when printing to the log or by \x`\write` primitive command. + +* \y`\endlinechar=`\code{`}`^^M`. + This character is appended to the end of each input + line. Tokenizer converts it (Ctrl-M character) to the space token. + +* \y`\time=now`, + \y`\day=now`, + \y`\month=now`, + \y`\year=now`. The values about current time/date are set here when \TeX/ + starts to process the document. The \x`\time` + counts minutes after midnight. + +* \y`\overfullrule=5pt`. A rectangle to this width is appended after each + \ii overfull/box overfull `\hbox`. + +* \y`\mathsurround=0pt` is space inserted around formula from internal math mode. + +* \y`\abovedisplayskip=12pt plus3pt minus9pt`, + \y`\abovedisplayshortskip=0pt plus3pt`, + \y`\belowdisplayskip=12pt plus3pt minus9pt`, + \y`\belowdisplayshortskip=7pt plus3pt minus 4pt`. + These spaces are inserted above and below the formula generated in math display + mode. + +* \y`\tabskip=0pt` is used by `\halign` primitive command for creating tables. + +* \y`\output={\plainoutput}`, \y`\everypar={}`, \y`\everymath={}` + \y`\everydisplay={}`, + \y`\everyhbox={}` + \y`\everyvbox={}` + \y`\everycr={}`, + \y`\everyjob={}`. + These tokens lists are processed when algorithms of \TeX/ reach a corresponding + situation: opens output routine, paragraph, internal math mode, display + math mode, \x`\vbox`, \x`\hbox`. Or it is at the end of the line in the table or it + starts the job. +\enditems + +\sec[expand] Expandable primitive commands + +Notes about notation in this and the following sections. +If the documented command is from e\TeX{} extension +(i.\,e.\ implemented in pdf\TeX, Xe\TeX/ +and lua\TeX) then one * is prefixed. If it is from pdf\TeX/ extension +(implemented in Xe\TeX/ and lua\TeX/ too) then two ** are prefixed. +If it is~a~lua\TeX/ only command then three *** are prefixed. + +\begitems +* \i string `\string|;` expand to an \x`\escapechar` (if positive) + followed by the name of the control sequence. All characters of the output + are \"other characters\c{12}", only spaces (if exist) + are kept as space tokens {\char9251}\c{10}. + +* \*\*\*\i csstring `\csstring|;` works like`\string` but without + `\escapechar`. + +* \*\i detokenize `\detokenize/.{|};` re-tokenizes all tokens in the text. + Control sequences used in are re-tokenized like `\string` primitive, spaces + are tokens {\char9251}\c{10} and all other tokens are set as \"other + characters\c{12}". + +* \i the `\the|;` expands to the value of the register. Examples were in + previous section. The output is tokenized like the output of `\detokenize`. + The exception is `\the|;`: the output is the value + of the `` without re-tokenizing and expand processor + does not expand this output in `\edef`\, `\write`, `\message` etc. arguments. + +* \i scantoken `\scantokens/.{|};` re-tokenizes using actual + tokenizer setting. The behavior is the same as to write `` to a + virtual file and reading this file immediately. + +* \*\*\*\i scantextokens `\scantextokens/.{|};` is the same as + `\scantokens` but removes problems with end-of-virtual-file. + +* \i meaning `\meaning|;` expands to the meaning of the ``. The text is + tokenized like in the `\detokenze` output. + +* \i csname \i endcsname `\csname\endcsname` creates a control sequence with name . + If it is not defined, then it gets the `\relax` meaning. + For example `\csname TeX\endcsname` is the same as `\TeX`. + The `` must be expandable to characters only. Non-expandable + control sequences (a primitive command at the main processor level, a register, + a character constant, a font selector) are disallowed here. \TeX/ reports the + error `missing \encsname` when this rule isn't compliant. + + Example: `\csname foo:\the\mynumber\endcsname` expands to control sequence + `\foo:42` if the `\mynumber` is a register with the value 42. + Another example: macro programmer should implement key/value dictionary + using this primitive: +\begtt +\def\keyval #1 #2 {\expandafter\def\csname dict:#1\endcsnme{#2}} +\def\value #1 {\csname dict:#1\endcsname} +\kyval Peter 21 % key=Peter, value=21, saved to the dictionary + % it does \def\dict:Peter{21} +\value Peter % expands to \dict:Peter and it expands to 21. +\endtt + +* \i expandafter `\expandafer|;` does transformation + ``. The token processor will expand `` + after such transformation. The `` is only the first level of + expansion. For example, a macro is transformed to its `` + but without expansion of `` at this time. + Or `\csname...\endcsname` pair creates a control sequence but does not + expand it at this time. + + If `` is not expandable then \x`\expandafter` silently does + nothing. + + The example above (the `\keyval` macro) shows usage of \x`\expandafter`. + We need not define `\csname` by `\def`, we want to define + a `\dict:key`. The \x`\expandafter` helps here. + + The `` should be another \x`\expandafter`. We can see + \x`\expandafter` chains in many macro files. For example + `\expandafter A\expandafter B\expandafter CD` is processed as + `ABC`. + + The `/.{|};` syntax rule enables to prepare `|;` using + `\expandafter`(s). For example \i detokenize `\detokenize{\macro}` expands to + `\`\c{12}`m`\c{12}`a`\c{12}`c`\c{12}`r`\c{12}`o`\c{12}. But if you need to detokenize + the `` of the `\macro` then use + `\detokenize\expandafter{\macro}`. Not only `\expandafter`s should be + here. Expand processor does full expansion here until the opening brace + `{`\c{1} is found. + +* \i if \i else \i fi The general rule for all `\if*` commands is + `/\else.\fi`. + The `` is evaluated and `` or `` + is skipped or processed depending on the result of ``. + When the expand processor is skipping the text due to `\if*` command then it + expands nothing in the skipped text. But it is noticing all control + sequences with meaning `\if*`, `\else` and `\fi` during skipping in order + to skip correctly all nested `\if*.../\else....\fi` constructions. + + The following ``s are possible: + \_printitem={$\circ$\enspace} + +* \i if `\if` is true if + \begitems \removelastskip \style a + * both tokens are characters with the same Unicode (or ASCII code in classical \TeX) or + * both tokens are control sequences + (with arbitrary meaning but not \"the character") or + * one token is a character, second is a control sequence equal to the character (by `\let`) or + * both tokens are control sequences, their meaning (set by `\let`) is the same character code. + \enditems + \removelastskip + \noindent Example: you can say `\let\test=a` then `\if\test a` returns true. + +* \i ifx `\ifx|;` is true if the meanings of `` + and `` are the same. + +* \i ifnum `\ifnum`. The `` could be + \code{<} or \code{=} or \code{>}. It returns true if the comparison of two + numbers is true. + +* \i ifodd `\ifodd` returns true if the `` is odd. + +* \i ifdim `\ifdim` The `` could be + \code{<} or \code{=} or \code{>}. It returns true if the comparison of two + dimensions is true. + +* \x`\iftrue` returns constantly true, \x`\iffalse` returns constanty false. + +* \x`\ifhmode`, \x`\ifvmode`, \x`\ifmmode` -- + true if the current mode is horizontal, vertical, math. + +* \x`\ifinner` returns true if the current mode is internal vertical, internal + horizontal or internal math mode. + +* \i ifhbox `\ifhbox`, + \i ifvbox `\ifvbox`, \i ifvoid `\ifvoid` + returns true if the specified `` represents \x`\hbox`, \x`\vbox`, void box + respectively. + +* \i ifcat `\ifcat` is true if catogory codes of `` + and `` equals. + +* \i ifeof `\ifeof` is true, of the file attached to the `` + by \x`\openin` primitive does not exist or the end of file was reached by + the \x`\read` primitive. + \_printitem{$\bullet$\enspace} + +* \*\i unless `\unless` negates the result of `` before + skipping or processing the following text. + +* \i ifcase `\ifcase\or\or...\or/\else.\fi`. + It processes the branch given by ``. It processes `` + (or nothing if no `` is declared) when a branch with given + `` does not exist. + +* \i noexpand `\noexpand|;`. + The expand processor does not expand the `` if it is expanding the + text in `\edef`, `\write`, `\message` or similar lists. + +* \*\i unexpanded `\unexpanded/.{|};` returns `` and applies + `\noexpand` to all tokens in the ``. + +* \*\i numexpr `\numexpr`, \i dimexpr \*`\dimexpr`. + Documented in the `` and `` syntax rules in the section~\ref[reg]. + +* \i number `\number`, \i romannumeral `\romannumeral` prints in decimal + digits or as a roman numeral (with lowercase letters). + +* \x`\topmark` (last from previous page), + \x`\firstmark` (first on current page), + \x`\botmark` (last on current page). They expand to the corresponding + \x`\mark` included in the current or previous page-box. + Usable for implementing running headers in the output routine. + +* \i fontname `\fontname` expands to the file name \*\*\*(or font name) of + the font given by its ``. The `\fontname\font` expands to + the file name of the current font. + +* \x`\jobname` expands to the name of the main file of this document (without + extension `.tex`). + +* \i input `\input` (classical \TeX) or \ `\input""` \ + or \ `\input{}` \ opens the given + `` and starts to read input from it. If the `` + doesn't exist then \TeX/ tries to open again \,{\def\,{\kern-1pt}`.tex`}. + If it doesn't exist even this, \TeX/ reports an error. + The alternative syntax with `"..."` or `{...}` allows having spaces in the file + names. + +* \i endinput `\endinput`. The current line is the last line of the inputted file. File + is closed and reading continues from the place where `\input` of this file + was started. `\endinput` done in the main file causes future reading from the + terminal and headache of users. + +* \*\*\*\i directlua `\directlua {}` runs a Lua script given in ``. + +\enditems + + +\sec[main] Primitive commands at the main processor level + +{\bf Commands used for declaration control sequences} + +\begitems +* \x`\def` \x`\edef` \x`\gdef` \x`\xdef` were documented in the section~\ref[def]. + +* \x`\long` is prefix, it can be used before `\def` `\edef` `\gdef` `\xdef`. + The declared macro accepts the control sequence `\par` in its parameters. + +* \*\x`\private` is prefix, it can be used before `\def` `\edef` `\gdef`, `\xdef`. + The declared macro is not expanded by the expand processor in \x`\write`, + \x`\message`, \x`\edef` etc. parameters. + +* \x`\outer` is prefix, can be used before `\def` `\edef` `\gdef`, `\xdef`. + The declared macro must be used only when the main processor is in the context + {\em do something} or \TeX/ reports an error. + +* \x`\global` is a prefix, it can be used before each assignment (commands + from this subsection and `=` settings). The + assignment is global regardless of the current group. + +* \i chardef `\chardef|;=`, + \i mathchardef `\mathchardef|;=` + \ declares a constant . When the main processor is in the context + \"do something" and it gets a \x`\chardef`-ed control sequence, it prints + the character with Unicode (ASCII code) to the typesetting output. + If it gets a \x`\mathchardef`-ed control sequence, it prints a math object (it works + only in math mode, not documented here). + +* \i countdef `\countdef|;=` declares `` as + an equivalent to the `\count` which is a register of counter type. + The `` here means an address in the + array of registers of counter type. The `\count0` is reserved for the page + number. The macro programmer uses rarely direct addresses (1 to 9), more + common is using the allocation macro `\newcount|;`. + +* \x`\dimendef`, \x`\skipdef`, \x`\muskipdef`, \x`\toksdef` followed by + `|;=` + declare analogically + equivalents to \i dimen `\dimen`, \i skip `\skip`, + \i muskip `\muskip` and \i toks `\toks`. + Usage of allocation macros \x`\newdimen`, \x`\newskip`, \x`\newmuskip`, + \x`\newtoks` are preferred. + +* \i font `\font|;=/.` declares + `` of a font implemented in the `.tfm`. The + `` can be `at` or `scaled`. + The `` equal to {\tt 1000} means 1:1. + New syntax (supported by Unicode engines) is + +\begtt \catcode`\|=13 \catcode`\/=13 \catcode`\<=13 \Blue +\font|;="/:." /. % or +\font|;="[]/:." /. +\endtt +% + The `` is file name without `.otf` nor `.ttf` extension. + The `` are font features prefixed by `+` or `-` and + separated by semicolon. The {\let\,=\relax `otfinfo -f .otf`} command + (on command line) can list them. + Lua\TeX/ supports alternative syntax: `{...}` instead of `"..."`. + Example: `\font\test={[texgyretermes-regular]:+onum;-liga} at12pt`. + +* \i let `\let|=;` sets to the `` + the same meaning as `` has. The `` can be whatever, a + character or a control sequence. + +* \i futurelet `\futurelet|;` works in two steps. + In the first step it does `\let|=;` and in the + second step `` is processed with activated token + processor. Typically `` is a macro that needs to know the next token. +\enditems + +\noindent {\bf Commands for box manipulation} + +\begitems +* \i hbox `\hbox{}` or `\hbox to{}` or `\hbox spread{}` + creates a box. The material inside this box is a `` + generated by `` in the horizontal mode in a group. The width of the box is natural width + of the `` or `` given by \ii to `to` parameter or + it is spread by `` given by \ii spread `spread` + parameter. The height of the box is the maximum of heights of all elements in + the ``. The depth of the box is maximum of depths of all + such elements. These elements are put to the common baseline (exceptions + can be given by \x`\lower` or \x`\raise` commands). + +* \i vbox `\vbox{}` or `\vbox to{}` + or `\vbox spread{}` + creates a box. The material inside this box is a `` + generated by `` in the vertical mode in a group. The height of the + box is the natural height of the `` (eventually modified by values + from \ii to `to` or \ii spread `spread` parameters) without the depth of the last + element. The depth of the last element is set as the depth of the box. + The width of the box is the maximum of widths of elemens in the ``. + All elements are put to the + common left margin of the box (exceptions can be given by \x`\moveleft` or + \x`\moveright` commands). + +* \i vtop `\vtop{}` (with optional `to` or `spread` + parameters) is equal as `\vbox`, + but the baseline of the resulting box goes through the baseline of the first element in + the `` (note that `\vbox` has its baseline equal to the + the baseline of the last element inside). + +* \i vcenter `\vcenter{}` (with optional `to` or `spread` + parameters) is equal to + `\vbox`, but its \ii math/axis {\em math axis}\fnote + {Math axis is a horizontal line which goes through centers of + and $-$ + symbols. Its distance from baseline is declared in the math font metrics.} + is exactly in the middle of the box. So its baseline is appropriately shifted. + The `\vcenter` can be used only in math modes but given `` are + processed in vertical mode. + +* \i lower `\lower`, \i raise `\raise` move the `` up or down by + the `` in horizontal mode. + \i moveleft `\moveleft`, + \i moveright `\moveright` move the `` by + the `` in vertical mode. + +* \i setbox `\setbox=`. \TeX/ has a set of + \ii box/register {\em box registers} addressed by `` and + accessed via \i box `\box` or alternatives described below. + The `\setbox` command saves given `` to the register addressed by + ``. + + Macro programmers use only 0 to 9 `` directly. Other + addresses to box registers should be allocated by + the \i newbox `\newbox|;` macro. The `|;` + is equivalent to a ``, not to the box register itself. + + The `\setbox` command does an assignment, so \x`\global` prefix is needed + if you want to use the saved box outside the current group. + +* \i box `\box` returns the box from `` box + register. Example: you can do `\setbox0=\hbox{abc}`. This `\hbox` is + not printed but saved to the register 0. At different place you can use + `\box0` which prints `\hbox{abc}` or you can do + `\setbox0=\hbox{cde\box0}` which saves the `\hbox{cde\hbox{abc}}` + to the register~0. + +* \i copy `\copy` returns the box from + `` box register and keeps the same box in this box register. + Note that the \i box `\box` returns the + box and empties the register `` immediately. If you don't want + to empty the register, use `\copy`. + +* \i wd `\wd`, `\ht`, `\dp`. You can + measure or use the width, height and depth of a box saved in a register addressed + by ``. Examples `\mydimen=\ht0`, `\hbox to\wd0{...}`. + You can re-set the dimensions of a box saved in a register addressed by + ``. For example \i setbox `\setbox0=\hbox{abc}` `\wd0=0pt` `\box0` + gives the same result as \i hbox `\hbox to0pt{abc}` but without the warning about + \ii overfull/box overfull `\hbox`. + +* \i unhbox `\unhbox`, \kern-.4pt\i unvbox `\unvbox`, + \kern-.4pt\i unhcopy `\unhcopy`, \kern-.4pt\i unvcopy `\unvcopy` + do the same work as `\box` or `\copy` but they don't return the whole + box but only it contents, i.\,e.~a horizontal or vertical material. + Example: try to do \i setbox `\setbox0=\hbox{abc}` and later + `\setbox0=\hbox{cde\unhbox0}` saves + the \i hbox `\hbox{cdeabc}` to the box register~0. + + The \x`\unhbox` and \x`\unhcopy` commands return the \x`\hbox` contents and + \x`\unvbox`, \x`\unvcopy` commands return the \x`\vbox` contents. If incompatible + contents is saved then \TeX/ reports an error. You can test the type of + saved contents by \x`\ifhbox` or \x`\ifvbox`. + +* \i vsplit `\vsplit to` does a column break. + The `` saved in the box `` is broken + to a first part of `` height and the rest remains in the + box ``. The broken part is completed as `\vbox` which is the + result of this operation. For example, you can say `\newbox\column` + `\setbox\column=\vbox{...}` and later + `\setbox0=\vsplit\column to5cm`. The `\box0` is `\vbox` with first 5cm of + saved material. + +* \x`\lastbox` returns the last box in the current vertical or horizontal + material and removes it. +\enditems + +\noindent {\bf Commands for rules (lines in the typesetting output) and patterns} + +\begitems +* \x`\hrule` creates a horizontal line in current vertical + list. If it is used in a horizontal mode, it finishes the paragraph by + \x`\par` first. + `\hrule /width. /height. /depth.` creates (in + general, with given parameters) a full + rectangle (something like a box, but it isn't treated as the box) with given + dimensions. Default values are: \"width"=width of outer `\vbox`, + \"height"=0.4\,pt, \"depth"=0\,pt. + {\emergencystretch=2em\par} + +* \x`\vrule` creates a vertical line in current horizontal + list. If it is used in a vertical mode, it opens the horizontal mode + first. + `\vrule /width. /height. /depth.` creates (in + general, with given parameters) a full rectangle with given + dimensions. Default values are: \"width"=0.4\,pt, + \"height"=height of outer `\hbox`, \"depth"=depth of outer `\hbox`. + {\emergencystretch=2em\par} + + The optional parameters of `\hrule` and `\vrule` could be specified in + arbitrary order and they can be specified more than once. In such a case, + the rule \"last wins" is applied. + +* \i leaders `\leaders` crates a glue + (maybe shrinkable or stretchable) filled by a full rectangle. + The `` is \x`\vrule` or \x`\hrule` (maybe with its optional parameters). + If the `` is specified by \x`\hskip` command + (maybe with its optional parameters) + or by its alternatives \x`\hss`, \x`\hfil`, \x`\hfill`, then the resulting glue + is horizontal (can be used only in horizontal mode) and its dimensions + are: width derived from ``, height plus depth derived from ``. + If the `` is specified by \x`\vskip` command + (maybe with its optional parameters) + or by its alternatives \x`\vss`, \x`\vfil`, \x`\vfill`, then the resulting glue + is vertical (can be used only in vertical mode) and its dimensions + are: height derived from ``, width derived from ``, depth is zero. + +* \i leaders `\leaders` creates a vertical or horizontal glue + filled by a pattern of repeated ``. The positions of boxes are + calculated from the boundaries of the outer box. It is used for dots patterns + in the table of contents. + \i cleaders `\cleaders` does the same, but the pattern of boxes is + centered in the space derived by the . Spaces between boxes are not~inserted. + \i xleaders `\xleadres` does the same, but the spaces between + boxes are inserted equally. +\enditems + +\noindent {\bf More commands for creating something in typesetting output} + +\begitems +* \x`\par` closes horizontal mode and finalizes a paragraph. +* \x`\indent`, \x`\noindent`. They leave the vertical mode and open paragraph + with/without paragraph indentation. If horizontal mode is current then + `\indent` inserts an empty box of `\parindent` width, `\noindent` does + nothing. +* \x`\hskip`, \x`\vskip`. They insert a horizontal/vertical glue. Documented in + the section~\ref[boxes]. +* \x`\hfil`, \x`\hfill`, \x`\hss`, \x`\vfil`, \x`\vfill`, \x`\vss` are alternatives + of \x`\hskip`, \x`\vskip`. +* \i kern `\kern` puts nonbreakable horizontal/vertical space + depending on the current mode. +* \i penalty `\penalty` puts the penalty `` to the current + horizontal/vertical list. +* \i char `\char` prints the character with code + \kern-2pt``\kern-2pt. The + \"character itself" does the same. +* \i accent `\accent` places an accent with code + `` above the ``. +* \ii -space `\`{\tt\char9251} is \ii control/space control space. In + horizontal mode, it inserts the space glue (like normal space but without + modification by the \x`\spacefactor`). In vertical mode, it opens horizontal + mode and puts the space. Note that normal space does nothing in vertical + mode. +* \i discretionary `\discretionary{
}{}{}` 
+  works in horizontal mode. It prints ``
+  in normal cases but if there is a line break then `
`
+  is used before and `` after the breaking point.
+  German Zucker/Zuk-ker (sugar) can be implemented by 
+  `Zu\discretionary{k-}{k}{ck}er`.
+* \ii -hyphen `\-` is equal to \i hyphenchar 
+  `\discretionary{\char\hyphenchar}{}{}`.
+  The `\hyphenchar` is used as a hyphenation character. It is set
+  to \x`\defaulthyphenchar` value when the font is loaded, but it can be changed.
+* \ii -italiccorr \code{\\/} does an
+  \ii italics/correction italics correction. 
+  It puts a little space if the last character is slanted.
+* \x`\unpenalty`, \x`\unskip` removes last penalty / last glue
+  from the current horizontal/vertical list.
+* \i vadjust `\vadjust{}`. It works in horizontal mode. The ``
+  must create a `` and `\vadjust` saves a pointer to this list
+  into the current horizontal list. When `\par` creates lines of the paragraph
+  and distributes them to a vertical list, each line with the pointer from
+  `\vadjust` has the corresponding `` immediately appended 
+  after this line.
+* `\insert{}`. The `` create a `` and
+  `\insert` saves a pointer to such `` into the current list.
+  The output routine can work with such ``\kern-2pts. The footnotes or
+  \ii floating~object {\em floating objects} (tables, figures) 
+  are implemented by the `\insert` primitive.  
+* \i halign `\halign{\cr\cr\cr...\cr\cr}`
+  creates a table of boxes in vertical mode. The `` declares
+  one or more column patterns separated by `&`\c4. The rows use the same
+  character to separate the items of the table in each row. The `\halign`
+  works in two passes. First it saves all items to boxes and the second pass
+  performs `\hbox to`~$\Blue w$ for each saved items, where $\Blue w$ 
+  is the maximal width of items in each actual column. 
+
+  Detailed documentation of `\halign` is out of scope of this manual.
+  Only one example follows: the macro `\putabove` puts `#1` above `#2`
+  centered. The width of resulting box is equal to max of widths of these 
+  two parameters. The `` `\hfil##\hfil` means that the items
+  will be centered:
+  `\def\putabove#1#2{\vbox{\halign{\hfil##\hfil\cr#1\cr#2\cr}}}`.
+
+* \x`\valign` does the same as `\halign` but rows $\leftrightarrow$ columns.
+  It is not used commonly.
+
+* \x`\cr`, \x`\crcr`, \x`\span`, \x`\omit`, \i noalign `\noalign{}`
+  are primitives used by `\halign` and `\valign`. 
+
+\enditems
+
+\noindent {\bf Commands for registers calculation}
+
+\begitems
+* \i advance `\advance/by.` does (formally)
+  `=+`. The `` is counter type or dimen
+  type. The `` is `` or `` (depending on type of the
+  ``).
+* \i multiply `\multiply/by.` does
+  `=*`.
+* \i divide `\divide/by.` does
+  `=`\code{/}``. If the `` is 
+  number type then the result is truncated.
+* See \*`\numexpr` and \*`\dimexpr`, expandable primitives documented in the
+  sections~\ref[reg] and~\ref[expand].
+\enditems
+
+\noindent {\bf Internal codes}
+
+\begitems
+* \i catcode `\catcode` is category code of the character with
+  `` code. Used by tokenizer.
+* \i lccode `\lccode` is lower case alternative to the
+  `\char`. If it is zero then lower case alternative doesn't exist
+  (for example for punctuation). Used by `\lowercase` primitive and when
+  breaking points are calculated from hyphenation patterns.
+* \i uccode `\uccode` is upper case alternative to the
+  `\char`. If it is zero, then the upper case alternative doesn't exist.
+  Used by `\uppercase` primitive.
+* \i lowercase \i uppercase `\lowercase/.{|};`, \
+  `\uppercase/.{|};` transform `|;` to
+  lowercase / uppercase using current `\lccode` or `\uccode` values.
+  Returns transformed `|;` where catcodes of tokens and 
+  tokens of type `` are unchanged.
+* \i sfcode `\sfcode` is spacefactor code of the `\char`.
+  The `\spacefactor` register keeps (roughly speking) 
+  the `\sfcode` of the last printed character. The glue between words
+  is modified (roughly speaking) by this `\spacefactor`. The value
+  1000 means factor 1:1 (no modification is done). It is used for enlarging spaces
+  after periods and other punctuation in English texts.\fnote{
+  This feature is not compliant with another typographical traditions, so
+  `\frenchspacing` macro which sets all `\sfcodes` to 1000 is used very often.}
+  {\emergencystretch=2em\par}
+\enditems
+
+\noindent {\bf Commands for reading or writing text files}
+
+\begitems
+* Note, that main input stream is controlled by `\input` and `\endinput`
+  expandable primitive commands documented in the section~\ref[expand].
+
+* \i openin `\openin=`
+  (or `\openin={}`) opens the
+  file `` for reading and creates a file descriptor
+  connected to the ``\fnote
+  {Note that `` is an addresses to the file descriptor. Macro
+  programmers don't use these addresses directly but by 
+  \i newread `\newread|;` and 
+  \i newwrite `\newwrite|;` allocation macros.}. 
+  If the file doesn't exist nothing happens but
+  macro programmer can test this case by `\ifeof`.
+
+* \i read `\readto|;` does
+  `\def|{};` where
+  the `` is tokenized next line from the file declared by
+  `\openin` as ``.
+
+* \i openout `\openout=`
+  (or `\openout=""`) \  opens the `` for
+  writing and creates a file descriptor connected to ``.
+  If the file does exist, then its contents are removed.
+  {\emergencystretch=2em\par}
+
+* \i write `\write|{};` writes a line of ``
+  to the file declared by `\openout` as ``. But this isn't done
+  immediately. \TeX/ does not know the value of the current page
+  when the `\write` command is processed because
+  the paragraph building and page building algorithms are processed
+  asynchronously. But a macro programmer typically needs to save current 
+  page to the file in order to read it again and to create 
+  a Table of contents or an Index.
+
+  `\write|{};` saves `|;` into memory and puts a
+  pointer to this memory into the typesetting output. When the page is shipped
+  out (by output routine), then all such pointers from this page are
+  processed: the `` is expanded at this time and its expansion
+  is saved to the file. If (for example) the `` includes 
+  `\the\pageno` then it is expanded to the correct page number of this page. 
+
+* \i closein `\closein`, \i closeout `\closeout`
+  closes the open file. It is done automatically when \TeX/ terminates its
+  job.
+
+* \x`\immediate` is the prefix. It can be used before `\openout`, `\write` and
+  `\closeout` in order to do the desired action immediately (without waiting to
+  the output routine). 
+\enditems
+
+\noindent {\bf Others primitive commands}
+
+\begitems
+* \x`\relax` does nothing. Used for terminating uncomplete optional
+  parameters, for example.
+* \x`\begingroup` opens group, \x`\endgroup` closes group. 
+  The `{`\c1 and `}`\c2 does the same but moreover, they are syntactic
+  constructors for primitive commands and math lists (in math mode).
+  These two types of groups (declared by mentioned commands or
+  by mentioned characters) cannot be mixed, i.\,e.\ 
+  `\begingroup...}` gives an error. Plain \TeX/ declares
+  \x`\bgroup` and \x`\egroup` control sequences as an equivalent to
+  `{`\c1 and `}`\c2. They can be used instead  `{`\c1 and~`}`\c2 when we
+  need to open / close a group, to create a math list or when a box is constructed.
+  For example `\hbox\bgroup\egroup` is syntactically correct.
+* \i aftergroup `\aftergroup|;` saves the `|;` and puts it
+  back in the input queue immediately after the current group is closed. 
+  Then expand processor expands it (if it is expandable). More
+  `\aftergroup`s in one group creates a queue of `|;`s used after
+  the group is closed.
+* \i afterassignment `\afterassignment|;` saves the `|;`
+  and puts it back immediately after a following assignment (`=`,
+  `\def` etc.) is done.
+* \x`\lastskip`, \x`\lastpenalty` returns the value of last element in the
+  current horizontal or vertical list if it is glue / penalty. It returns
+  zero value if the element is not found as the last.
+* \x`\ignorespaces` ignores spaces in horizontal mode until
+  next primitive command occurs.
+* \i mark `\mark{}` saves `` to memory and puts a pointer to it in the
+  typesetting output. The `` is used as expansion output of
+  \x`\firstmark`, \x`\topmark` and \x`\botmark` expansion primitives in output
+  the routine.
+* \i parshape `\parshape`% 
+  {\def<#1>{\,$\langle\it#1\rangle$\,}%
+  `...`
+  enables to set arbitrary shape of the paragraph. The `` 
+  declares the amount of data: the `` pairs of ``s follow.
+  The $i$-th line of the paragraph is shifted by `` to right and
+  its width is ``.} The `\parshape` data are re-set after
+  each paragraph to zero values (normal paragraph).
+* \i special `\special{}` puts the message `` to the typesetting output. It
+  behaves as a zero-dimension pointer to `` and it can be read by
+  printer drivers. It is recommended to not use this old technology
+  when PDF output is created directly.
+* \i shipout `\shipout` outputs the `` as one page. Used in the 
+  \ii output/routine output routine.
+* \x`\end` completes the last page and terminates the job.
+* \x`\dump` dumps the memory image to the `\jobname.fmt` and terminates the job.
+* \i patterns `\patterns{}` reads hyphenation patterns for current 
+  \x`\language`.
+* \i hyphenation `\hyphenation{}` reads hyphenation exceptions for
+  current \x`\language`.
+* \i message `\message{}` prints `` on the terminal and to the 
+  log file.
+* \i errmessage `\errmessage{}` behaves like `\message{}` but
+  \TeX/ treats it as an error.
+* Job processing modes can be set by \x`\scrollmode` (don't pause at the
+  errors), \x`\nonstopmode` (don't pause at the errors and missing files),
+  \x`\batchmode` (\x`\nonstopmode` plus no output on the terminal). Default is
+  \x`\errorstopmode` (stop at errors).
+* \x`\inputlineno` includes the number of current line from current inputted
+  file.
+* \i show `\show|;`, \ \i showbox `\showbox`, 
+  \ \x`\showlists` \ and \ 
+  \i showthe `\showthe|;` \ are tracing commands. \TeX/ prints desired result
+  on the terminal and to the log file and pauses.
+\enditems
+
+\noindent {\bf Commands specific for PDF output} 
+(available in pdf\TeX, \XeTeX/ and lua\TeX)
+
+\begitems
+* \i pdfliteral `\pdfliteral{}` puts the `` interpreted 
+  in a low level PDF language to the typesetting output. All PDF constructs
+  defined in the PDF specification are allowed. The dimensions of
+  the `\pdfliteral` object in the output are considered zero. So, if 
+  `` moves the current typesetting point then the notion about its
+  position from \TeX/ point of view differs from the real position. 
+  A good practice is to close `` to `q...Q` PDF commands.
+  The command `\pdfliteral` is typically 
+  used for generating graphics and for linear transformation.
+* \i pdfcolorstack `\pdfcolorstack{}` (where `` is `push`
+  or `pop` or `set`) behaves like `\pdfliteral{}` and it is used for
+  color switchers. For example when `` is `1 0 0 rg` then red color is
+  selected. \TeX/ sets the colors stack at the top of each page to the
+  colors stack opened at the bottom of the previous page.
+* \i pdfximage 
+  `\pdfximage` `/height.` `/depth.` `/width.` `/page.{}`
+  loads the image from `` to the PDF output and returns the
+  number of such data object in the \x`\pdflastximage` register. Allowed
+  formats are PDF, JPG, PNG. The image is not drawn at this moment. Macro
+  programmer can save `\mypic=\pdflastximage` and draw the image by
+  \i pdfrefximage `\pdfrefximage\mypic` (maybe repeatedly). Data of 
+  the image are loaded to PDF output only once. 
+  The `\pdfximage` allows more parameters,
+  see pdf\TeX/ documentation.
+* \i pdfsetmatrix {\def<#1>{$\,\langle{\it#1}\rangle\,$}`\pdfsetmatrix {}`
+  multiplies the current transformation matrix (used for linear
+  transformations) by `\matrix{&\cr &}`.}
+* \i pdfdest `\pdfdest name{