tex-nutshell (17mar21) (branch)

git-svn-id: svn://tug.org/texlive/branches/branch2020.0@58486 c570f23f-e606-0410-a88d-b1316a301751

2 files changed, 58 insertions, 34 deletions

diff --git a/Master/texmf-dist/doc/plain/tex-nutshell/tex-nutshell.pdf b/Master/texmf-dist/doc/plain/tex-nutshell/tex-nutshell.pdf
index 35e5beae145..7355c2ebbd3 100644
--- a/Master/texmf-dist/doc/plain/tex-nutshell/tex-nutshell.pdf
+++ b/Master/texmf-dist/doc/plain/tex-nutshell/tex-nutshell.pdf
diff --git a/Master/texmf-dist/doc/plain/tex-nutshell/tex-nutshell.tex b/Master/texmf-dist/doc/plain/tex-nutshell/tex-nutshell.tex
index 1b69d3160dc..13b9ebfdf27 100644
--- a/Master/texmf-dist/doc/plain/tex-nutshell/tex-nutshell.tex
+++ b/Master/texmf-dist/doc/plain/tex-nutshell/tex-nutshell.tex
@@ -8,7 +8,7 @@
 \def\thed#1{\ifnum#1<10 0\fi\the#1}
 
 \catcode`<=13
-\def<#1>{{\def\ { }\iindex{:#1}\iis {:#1} {$\langle\hbox{\it#1}\rangle$}}%
+\def<#1>{{\def\_dsp { }\iindex{:#1}\iis {:#1} {$\langle\hbox{\it#1}\rangle$}}%
    $\def\,{\hskip1.5pt plus.3pt minus1.2pt}\,\langle\hbox{\it#1}\rangle\,$}
 \def\l#1>{$\def\,{\hskip1.5pt plus.3pt minus1.2pt}\,\langle\hbox{\it#1}\rangle\,$}
 \everyintt={\catcode`<=13 \Blue}
@@ -21,9 +21,9 @@
 \adef|#1;{{\Red#1}}
 \toksapp\everyintt{\catcode`\/=13 \catcode`\|=13}
 \catcode`\/=12 \catcode`\|=12
-\adef\%#1\par{{\adef\%{\%}\Green\%#1}\par}
+\def\comment#1\par{{\adef\%{\%}\Green\%#1}\par}
 \catcode`\%=14
-\toksapp\everytt{\catcode`\%=13}
+\toksapp\everytt{\adef\%{\comment}}
 
 \def\*{*}
 \def\c#1{$_{#1}$}
@@ -70,8 +70,8 @@ document that presents these basic principles because \LaTeX/ manuals
 typically don't distinguish between \TeX/ features and features specially
 implemented by \LaTeX/ macros. 
 
-I would like to express my special thank to Barbara Beeton who read my text
-very carefully and suggested hundreds language corrections and improvements
+I would like to express my special thanks to Barbara Beeton who read my text
+very carefully and suggested hundreds of language corrections and improvements
 and also discovered many of my real mistakes. Thanks to her, my text is
 better. But if there are any other mistakes then they are only mine and I'll be
 pleased if you send me a bug report in such case.  
@@ -195,19 +195,19 @@ They implement classical \TeX/ algorithms with various extensions:
 * \ii pdfTeX pdf\TeX/ -- an extension supporting PDF output directly and
              micro-typographical features,
 * \ii XeTeX \XeTeX/ -- an extension supporting Unicode and PDF output, 
-* \ii luaTeX lua\TeX/ -- an extension supporting Lua programming, Unicode,
+* \ii luaTeX Lua\TeX/ -- an extension supporting Lua programming, Unicode,
             micro-typographical features and PDF output.
 \enditems
 
 Each of them is 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,
+example the command `luatex -ini macros.ini` starts Lua\TeX/ at ini-\TeX/ state,
 reads the `macros.ini` file and the final `\dump` command is supposed here to create
 a format `macros.fmt`. Then a user can use the command `luatex -fmt macros document` to
 load `macros.fmt` and process the `document.tex`.
-Or the command `luatex document` processes lua\TeX/ with `document.tex` and 
+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: 
+`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}.
 
@@ -296,7 +296,7 @@ If you need to print these special characters you can use
 \"print this character" in all typical \TeX/ formats.
 Another possibility is to use a verbatim environment (it depends on the used format) 
 Last alternative: you can use \i csstring {\let\,=\relax`\csstring\<character>`} 
-in lua\TeX/, because lua\TeX/ disposes
+in Lua\TeX/, because Lua\TeX/ disposes
 with the primitive command `\csstring` which converts `\<character>`
 to `<character>`\c{12}.
 
@@ -362,7 +362,7 @@ The tokenizer converts two `^`\c7`^`\c7 characters followed by an ASCII uppercas
 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 a one-byte code, for example, `^^0d` is Ctrl-M too 
-because it has code 13. Moreover, the tokenizer of \XeTeX/ or lua\TeX/ converts
+because it has code 13. Moreover, the 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 a given Unicode.
@@ -449,7 +449,7 @@ alternatives), \i hrule `\hrule`, \i end `\end` and the plain \TeX/ macro \i bye
 Each assignment to registers, declaration macros or font selecting is local
 in groups. When the current group ends then the assignments made inside the
 group are forgotten and the values in effect before this group was opened are restored.
-The groups can be delimited by `{` and `}` pair or by \i begingroup `\begingroup` and 
+The groups can be delimited by `{`\c1 and `}`\c2 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. 
@@ -788,7 +788,18 @@ then the number of `#` must be doubled for inner declaration. Example:
 \goodbye Eric John         % expands to: Eric says: good bye John.
 \endtt
 
-Note the `%` characters used in the `\defmacro` definition. They mask
+The exact implementation of the feature above: when \TeX/ reads macro body
+(during `\def`, `\edef`, `\gdef`, `\xdef`) then each double `#`\c6  is converted 
+to single `#`\c6 and each (unconverted yet) single `#`\c6 followed by a digit is
+converted to an internal mark of future parameter. This mark is replaced
+by real prameter when the defined macro is used. This rule of conversion of
+macro body has one exception: `\edef{...\the\toks...}` keeps the toks
+content unexpanded and without conversion of hashes. And there exists 
+a reverse conversion from internal marks to~`#`\c{12}<number> and 
+from `#`\c6 to `#`\c{12}`#`\c{12} 
+when \TeX/ writes macro body by \i meaning `\meaning` primitive.
+
+Note the `%` characters used in the `\defmacro` definition in the exmample above. They mask
 the end of lines. If you don't use them, then the space tokens are included here (generated
 by the tokenizer at the end of each line). The `<replacement text>` of `\defmacro` will be
 `<space>\def#1...{...}<space>` in such a case. Each usage of `\defmacro` 
@@ -917,7 +928,7 @@ type of the register (i.e.\ `<number>`, `<dimen>`, `<skip>` and `<toks>`) follow
 
 \begitems \let\_aboveliskip=\relax 
 * The `<number>` could be 
-\begitems \style -
+\begitems \style N
 * 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)
@@ -929,9 +940,9 @@ type of the register (i.e.\ `<number>`, `<dimen>`, `<skip>` and `<toks>`) follow
   It returns the code of the `<character>`. Examples:
   \code{`}`A` or one-character control sequence \code{`\\A}).
   Both examples represent the number 65. The Unicode of the character 
-  is taken here if lua\TeX/ or \XeTeX/ is used;
+  is taken here if Lua\TeX/ or \XeTeX/ is used;
 * \i numexpr `\numexpr<num. expression>`.\fnote
-  {This is a feature of the $\varepsilon$\TeX/ extension. It is implemented in pdf\TeX, \XeTeX/ and lua\TeX.}
+  {This is a feature of the $\varepsilon$\TeX/ extension. It is implemented in pdf\TeX, \XeTeX/ and Lua\TeX.}
   The `<num. expression>` uses operators `+`, `-`, `*` and \code{/} and
   brackets `(`, `)` in normal sense. The operands are `<number>`s. It
   is terminated by something incompatible with
@@ -939,8 +950,9 @@ type of the register (i.e.\ `<number>`, `<dimen>`, `<skip>` and `<toks>`) follow
   The `\relax` (if it is used as a separator) is removed.
   If the result is non-integer, then it is rounded (not truncated).
 \enditems
+  The rules 3)--6) can be terminated by one optional space.
 * The `<dimen>` could be
-\begitems \style -
+\begitems \style N
 * a register of dimen type or counter type;
 * a decimal number with an optional decimal point (and optional `+` or `-`
   prefixed) followed by `<dimen unit>`. The `<dimen unit>` is \ii pt `pt` (point)\fnote 
@@ -960,6 +972,7 @@ type of the register (i.e.\ `<number>`, `<dimen>`, `<skip>` and `<toks>`) follow
   syntactic rule of `<dimen expression>` or by `\relax`. The `\relax` (if it
   is used as a separator) is removed.
 \enditems
+  The rule 2) can be terminated by one optional space.
 * The `<skip>` could be:
 \begitems \style -
 * a register of glue type or dimen type or counter type;
@@ -1176,11 +1189,12 @@ detail).
   \y`\everyhbox={}`
   \y`\everyvbox={}`
   \y`\everycr={}`,
+  \*\y`\everyeof={}`,
   \y`\everyjob={}`.
   These token lists are processed when an algorithm of \TeX/ reaches a corresponding
   situations respectively: opens output routine, paragraph, internal math mode, display
-  math mode, \x`\vbox`, \x`\hbox`, is at the end of a line in a table, or
-  starts the job.  
+  math mode, \x`\vbox`, \x`\hbox`, is at the end of a line in a table,
+  at the end of an input file, or starts the job.
 \enditems
 
 \sec[expand] Expandable primitive commands
@@ -1188,15 +1202,17 @@ detail).
 Notes about notation are in this and the following sections. 
 If the documented command is from the $\varepsilon$\TeX{} extension 
 (i.e.\ implemented in pdf\TeX, \XeTeX/
-and lua\TeX) then one * is prefixed. If it is from the pdf\TeX/ extension
-(implemented in \XeTeX/ and lua\TeX/ too) then two ** are prefixed. 
-If it is~a~lua\TeX/ only command then three *** are prefixed.
+and Lua\TeX) then one * is prefixed. If it is from the pdf\TeX/ extension
+(implemented in \XeTeX/ and Lua\TeX/ too) then two ** are prefixed. 
+If it is~a~Lua\TeX/ only command then three *** are prefixed.
 
 \begitems
-* \i string `\string|<control sequence>;` expands 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 any exist)
-  are kept as space tokens {\char9251}\c{10}.  
+* \i string `\string|<control sequence>;` expands to \"the \x`\escapechar`"
+  followed by the name of the control sequence. \i escapechar \"The \x`\escapechar`" means a
+  character with code equal to \x`\escapechar` or nothing if its value is
+  out of range of character codes.
+  All characters of the output are \"other characters\c{12}", only spaces (if any exist)
+  are kept as space tokens {\char9251}\c{10}. 
 
 * \*\*\*\i csstring `\csstring|<control sequence>;` works like`\string` but without
   `\escapechar`.
@@ -1206,9 +1222,9 @@ If it is~a~lua\TeX/ only command then three *** are prefixed.
   are tokens {\char9251}\c{10}, and all other tokens are set as \"other
   characters\c{12}".
 
-* \i the `\the|<register>;` expands to the value of the register. Examples appear in the
+* \i the `\the<register>` expands to the value of the register. Examples appear in the
   previous section. The output is tokenized like of `\detokenize`.
-  The exception is `\the|<tokens register>;`: the output is the value
+  The exception is `\the<tokens register>`: the output is the value
   of the `<tokens register>` without re-tokenizing and the expand processor 
   does not expand this output in `\edef`, `\write`, `\message`, etc., arguments.
 
@@ -1342,6 +1358,9 @@ If it is~a~lua\TeX/ only command then three *** are prefixed.
 * \*\i unexpanded `\unexpanded/<expandafters>.`\z`{|<text>};` returns \z`<text>` and applies 
   `\noexpand` to all tokens in the \z`<text>`. 
 
+* \*\*\i expanded `\expanded{<tokens>}` expands `<tokens>` and
+  reads these expanded `<tokens>` again.
+
 * \*\i numexpr `\numexpr<num. expression>`, \i dimexpr \*`\dimexpr<dimen expression>`.
   Documented in the `<dimen>` and `<number>` syntax rules in section~\ref[reg].
 
@@ -1620,7 +1639,9 @@ If it is~a~lua\TeX/ only command then three *** are prefixed.
 * \x`\hskip`, \x`\vskip`. They insert a horizontal/vertical glue. Documented in
   section~\ref[boxes].
 * \x`\hfil`, \x`\hfill`, \x`\hss`, \x`\vfil`, \x`\vfill`, \x`\vss` are alternatives
-  of \x`\hskip`, \x`\vskip`. 
+  of \x`\hskip`, \x`\vskip`, see section~\ref[boxes].
+* \x`\hfilneg`, \x`\vfilneg` are shortcuts for `\hskip 0pt plus-1fil`
+  and `\vskip 0pt plus-1fil`.
 * \i kern `\kern<dimen>` puts unbreakable horizontal/vertical space 
   depending on the current mode.
 * \i penalty `\penalty<number>` puts the penalty `<number>` on the current
@@ -1850,7 +1871,7 @@ If it is~a~lua\TeX/ only command then three *** are prefixed.
 \enditems
 
 \noindent {\bf Commands specific for PDF output} 
-(available in pdf\TeX, \XeTeX/ and lua\TeX)
+(available in pdf\TeX, \XeTeX/ and Lua\TeX)
 
 \begitems
 * \i pdfliteral \z`\pdfliteral{<text>}` puts the \z`<text>` interpreted 
@@ -1916,7 +1937,7 @@ If it is~a~lua\TeX/ only command then three *** are prefixed.
 \enditems
 
 \noindent {\bf Microtypographical extensions}
-(available in pdf\TeX/, lua\TeX/ and not all of them in \XeTeX)
+(available in pdf\TeX/, Lua\TeX/ and not all of them in \XeTeX)
 
 \begitems
 * \i pdffontexpand 
@@ -1974,6 +1995,9 @@ If it is~a~lua\TeX/ only command then three *** are prefixed.
   a math `<formula>` and gives `<delimiter>`s around it with an appropriate size
   (compatible with the size of the formula). The `<delimiter>`s are typically
   brackets.
+* \*\i middle `\middle<delimiter>` can be used inside the <formula>
+  surronded by `\left`, `\right`. The given <delimiter> gets the same size
+  as delimiters declared by appropriate `\left`, `\right`.
 * Exponents and scripts are typically at the right side of the preceding
   math object. But if this object is a \"big operator" (summation, integral)
   then exponents and scripts are printed above and below this operator.
@@ -2186,7 +2210,7 @@ If it is~a~lua\TeX/ only command then three *** are prefixed.
 \iis plain~TeX/macros {plain \TeX/ macros}
 \iis OpTeX {\OpTeX}
 \iis pdfTeX {pdf\TeX}
-\iis luaTeX {lua\TeX}
+\iis luaTeX {Lua\TeX}
 \iis XeTeX {\XeTeX}
 \iis TeX/engines {\TeX/ engines}
 \iis -percent {{\code{\\\%}}}
@@ -2212,7 +2236,7 @@ If it is~a~lua\TeX/ only command then three *** are prefixed.
 \noindent
 Petr Olšák {\tt petr@olsak.net}\nl
 Czech Technical University in Prague\nl
-Version of the text: 0.5 (\the\year-\thed\month-\thed\day)
+Version of the text: 0.6 (\the\year-\thed\month-\thed\day)
 
 \break