tex-nutshell (3jun21)

git-svn-id: svn://tug.org/texlive/trunk@59448 c570f23f-e606-0410-a88d-b1316a301751

2 files changed, 69 insertions, 37 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 7355c2ebbd3..3e3c59b2f59 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 13b9ebfdf27..412313ca2db 100644
--- a/Master/texmf-dist/doc/plain/tex-nutshell/tex-nutshell.tex
+++ b/Master/texmf-dist/doc/plain/tex-nutshell/tex-nutshell.tex
@@ -32,12 +32,36 @@
 \enquotes
 
 % to index macros:
-\def\i #1 {\ii .#1 \iis .#1 {{\code{\\#1}}}}
+\def\i #1 {\makedest{#1}\ii .#1 \iis .#1 {\ilink[cs:#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=}
 \def\z`{`\let<=\l}
+\let\_cslinkcolor=\Blue
+
+% tex-nutshell.pdf includes destinations to the explanation of the primitive
+% control sequences and plain TeX macros in the form: "cs:sequence". For example,
+% you can try:
+%
+%    http://petr.olsak.net/ftp/olsak/optex/tex-nutshell.pdf#cs:hbox
+%
+% All such sequences are listed in the tex-nutshell.eref file. You can read
+% this eref file into your document and create external links to these
+% destinations.
+
+\newwrite \eref
+\immediate\openout\eref=\jobname.eref
+\def\makedest#1{}
+\def\makedestactive#1{%
+   \ifcsname cs:#1\endcsname \else
+      \immediate\write\eref{\string\Xeref{#1}}%
+      \dest[cs:#1]%
+      \sxdef{cs:#1}{}%
+   \fi
+}
+\def\noda{\def\makedest##1{}}
+\def\doda{\let\makedest\makedestactive}
 
 % Hyperlinks
 \hyperlinks\Red\Green
@@ -98,7 +122,7 @@ There are four types of meanings of control sequences:
   behavior of built-in algorithms (e.g., \i hsize `\hsize`, \i parindent `\parindent`,
   \i hyphenpenalty `\hyphenpenalty`). On the other hand \ii declared/register {\em declared registers} 
   are used by macros (e.g., \i medskipamount `\medskipamount` used in plain \TeX/ 
-  or \i ttindent `\ttindent` 
+  or {\doda\i ttindent `\ttindent`}
   used by \ii OpTeX \OpTeX/).
 * the control sequence can be a \ii primitive/command {\em primitive command}, which runs a built-in
   algorithm (e.g., \i def `\def` declares a macro, \i halign `\halign` runs the algorithm for
@@ -119,7 +143,7 @@ Example. When \TeX/ reads:
 \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
+{\doda\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` 
@@ -453,8 +477,8 @@ The groups can be delimited by `{`\c1 and `}`\c2 pair or by \i begingroup `\begi
 \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
+For example, plain \TeX/ declares the macros {\doda\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. A user can write:
 
 \begtt
@@ -859,7 +883,7 @@ syntax for `<math text>`. So, \LaTeX/ manuals or \LaTeX/ documents
 serve 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:
-`{<numerator>\over<denominator>}` but \LaTeX/ uses a macro \x`\frac` in the
+`{<numerator>\over<denominator>}` but \LaTeX/ uses a macro {\doda\x`\frac`} in the
 syntax `\frac{<numerator>}{<denominator>}`. 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 
@@ -1021,6 +1045,8 @@ internal unit `sp` is omitted.
 The summary of most commonly used primitive registers including their default
 value given by plain \TeX/ follows.
 
+\let\makedest=\makedestactive
+
 \begitems  \rightskip=0pt plus1fil
 * \y`\hsize=6.5in`,
   \y`\vsize=8.9in`
@@ -1077,7 +1103,7 @@ value given by plain \TeX/ follows.
 
 * \y`\looseness=0` allows us to create of a \"suboptimal" paragraph. The page-building
   algorithm tries to build the paragraph with \x`\looseness` lines more than
-  the optimal solution. If the \x`\tolerance` does not have a sufficiently large value
+  the optimal solution. If the {\noda\x`\tolerance`} does not have a sufficiently large value
   then this setting is simply ignored. It is reset to zero after each
   paragraph is completed.
 
@@ -1152,7 +1178,7 @@ detail).
   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 the \x`\write` primitive command.
+  the line when printing to the log or by the {\noda\x`\write`} primitive command.
 
 * \y`\endlinechar=`\code{`}`^^M`. 
   This character is appended to the end of each input
@@ -1193,7 +1219,7 @@ detail).
   \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,
+  math mode, {\noda\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
 
@@ -1226,7 +1252,7 @@ If it is~a~Lua\TeX/ only command then three *** are prefixed.
   previous section. The output is tokenized like of `\detokenize`.
   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.
+  does not expand this output in {\noda`\edef`, `\write`, `\message`}, etc., arguments.
 
 * \i scantoken `\scantokens/<expandafters>.`\z`{|<text>};` re-tokenizes \z`<text>` using the actual
   tokenizer setting. The behavior is the same as when writing \z`<text>` to a 
@@ -1332,15 +1358,15 @@ If it is~a~Lua\TeX/ only command then three *** are prefixed.
 
 * \i ifhbox `\ifhbox<box number>`, 
   \i ifvbox `\ifvbox<box number>`, \i ifvoid `\ifvoid<box number>`
-  returns true if the specified `<box number>` represents \x`\hbox`, \x`\vbox`, void box
+  returns true if the specified `<box number>` represents {\noda\x`\hbox`, \x`\vbox`}, void box
   respectively.
 
 * \i ifcat \z`\ifcat<token 1><token 2>` is true if the category codes of \z`<token 1>`
   and \z`<token 2>` are equal.
 
 * \i ifeof `\ifeof<file number>` is true if the file attached to the `<file number>`
-  by the \x`\openin` primitive does not exist, or the end of file was reached by
-  the \x`\read` primitive.
+  by the {\noda\x`\openin`} primitive does not exist, or the end of file was reached by
+  the {\noda\x`\read`} primitive.
   \_printitem{$\bullet$\enspace}
 
 * \*\i unless `\unless<if condition>` negates the result of `<if condition>` before
@@ -1353,7 +1379,7 @@ If it is~a~Lua\TeX/ only command then three *** are prefixed.
 
 * \i noexpand `\noexpand|<token>;`. 
    The expand processor does not expand the `<token>` if it is expanding the
-   text in `\edef`, `\write`, `\message` or similar lists. 
+   text in {\noda\x`\edef`, \x`\write`, \x`\message`} or similar lists.
 
 * \*\i unexpanded `\unexpanded/<expandafters>.`\z`{|<text>};` returns \z`<text>` and applies 
   `\noexpand` to all tokens in the \z`<text>`. 
@@ -1370,7 +1396,7 @@ If it is~a~Lua\TeX/ only command then three *** are prefixed.
 * \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. 
+  {\noda\x`\mark`} included in the current or previous page-box.
   Usable for implementing running headers in the output routine.
 
 * \i fontname `\fontname<font selector>` expands to the file name \*\*\*(or font name) of
@@ -1408,9 +1434,9 @@ If it is~a~Lua\TeX/ only command then three *** are prefixed.
 * \x`\long` is a prefix; it can be used before `\def`, `\edef`, `\gdef`, `\xdef`.
   The declared macro accepts the control sequence `\par` in its parameters.
 
-* \*\x`\private` is a 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`\protected` is a prefix; it can be used before `\def`, `\edef`, `\gdef`, `\xdef`.
+  The declared macro is not expanded by the expand processor in {\noda\x`\write`,
+  \x`\message`, \x`\edef`}, etc., parameters.
 
 * \x`\outer` is a prefix; it can be used before `\def`, `\edef`, `\gdef`, `\xdef`.
   The declared macro must be used only when the main processor is in the context 
@@ -1440,8 +1466,8 @@ If it is~a~Lua\TeX/ only command then three *** are prefixed.
   declare analogically 
   equivalents to \i dimen `\dimen<number>`, \i skip `\skip<number>`, 
   \i muskip `\muskip<number>` and \i toks `\toks<number>`. 
-  Usage of allocation macros \x`\newdimen`, \x`\newskip`, \x`\newmuskip`,
-  \x`\newtoks` are preferred.
+  Usage of allocation macros {\noda\x`\newdimen`, \x`\newskip`, \x`\newmuskip`,
+  \x`\newtoks`} are preferred.
 
 * \i font `\font|<font selector>;=<file name><space>/<size specification>.` declares
   `<font selector>` of a font implemented in the `<file name>.tfm`. The 
@@ -1482,7 +1508,7 @@ If it is~a~Lua\TeX/ only command then three *** are prefixed.
   parameter. The height of the box is the maximum of heights of all elements in
   the `<horizontal list>`. The depth of the box is the maximum of depths of all
   such elements. These elements are set on the common baseline (exceptions
-  can be given by \x`\lower` or \x`\raise` commands). 
+  can be given by {\noda\x`\lower` or \x`\raise`} commands).
 
 * \i vbox `\vbox{<cmds>}` or `\vbox to<dimen>{<cmds>}` 
   or `\vbox spread<dimen>{<cmds>}`
@@ -1493,8 +1519,8 @@ If it is~a~Lua\TeX/ only command then three *** are prefixed.
   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 `<vertical list>`.
   All elements are placed at the
-  common left margin of the box (exceptions can be given by \x`\moveleft` or
-  \x`\moveright` commands).
+  common left margin of the box (exceptions can be given by {\noda\x`\moveleft` or
+  \x`\moveright`} commands).
 
 * \i vtop `\vtop{<cmds>}` (with optional `to` or `spread`
   parameters) is the same as `\vbox`,
@@ -1525,7 +1551,7 @@ If it is~a~Lua\TeX/ only command then three *** are prefixed.
 
   Macro programmers use only 0 to 9 \z`<box numbers>` directly. Other
   addresses to box registers should be allocated by 
-  the \i newbox `\newbox|<control sequence>;` macro. The `|<control sequence>;`
+  the {\noda\i newbox `\newbox|<control sequence>;`} macro. The `|<control sequence>;`
   is equivalent to a `<box number>`, not to the box register itself.
 
   The `\setbox` command does an assignment, so the \x`\global` prefix is needed
@@ -1583,11 +1609,11 @@ If it is~a~Lua\TeX/ only command then three *** are prefixed.
 \begitems
 * \x`\hrule` creates a horizontal line in the current vertical
   list. If it is used in horizontal mode, it finishes the paragraph by
-  \x`\par` first. 
+  {\noda\x`\par`} first.
   `\hrule /width<dimen>. /height<dimen>. /depth<dimen>.` 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`,
+  dimensions. Default values are: \"width"~=width of outer \x`\vbox`,
   \"height"~=0.4\,pt, \"depth"~=0\,pt.
   {\emergencystretch=2em\par}
 
@@ -1597,24 +1623,24 @@ If it is~a~Lua\TeX/ only command then three *** are prefixed.
   `\vrule /width<dimen>. /height<dimen>. /depth<dimen>.` 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`.
+  \"height"~=height of outer `\hbox`, \"depth"~=depth of outer \x`\hbox`.
   {\emergencystretch=2em\par}
 
-  The optional parameters of `\hrule` and `\vrule` can be specified in
+  The optional parameters of \x`\hrule` and \x`\vrule` can 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<rule><glue>` creates a glue 
   (maybe shrinkable or stretchable) filled by a full rectangle.
   The `<rule>` is \x`\vrule` or \x`\hrule` (maybe with its optional parameters).
-  If the `<glue>` is specified by an \x`\hskip` command
+  If the `<glue>` is specified by an {\noda\x`\hskip`} command
   (maybe with its optional parameters)
-  or by its alternatives \x`\hss`, \x`\hfil`, \x`\hfill`, then the resulting glue
+  or by its alternatives {\noda\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 `<glue>`, height plus depth derived from `<rule>`.
-  If the `<glue>` is specified by a \x`\vskip` command
+  If the `<glue>` is specified by a {\noda\x`\vskip`} command
   (maybe with its optional parameters)
-  or by its alternatives \x`\vss`, \x`\vfil`, \x`\vfill`, then the resulting glue
+  or by its alternatives {\noda\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 `<glue>`, width derived from `<rule>`, depth is zero.
 
@@ -1759,7 +1785,7 @@ If it is~a~Lua\TeX/ only command then three *** are prefixed.
   (or `\openin`\,`<file number>`\,`=`\,`{<file name>}`) \ opens the
   file `<file name>` for reading and creates a file descriptor
   connected to the `<file number>`.\fnote
-  {Note that `<file number>` is an address to the file descriptor. Macro
+  {\noda Note that `<file number>` is an address to the file descriptor. Macro
   programmers don't use these addresses directly but by the
   \i newread `\newread|<control sequence>;` and 
   \i newwrite `\newwrite|<control sequence>;` allocation macros.} 
@@ -1813,7 +1839,7 @@ If it is~a~Lua\TeX/ only command then three *** are prefixed.
   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 equivalents to
+  {\noda\x`\bgroup` and \x`\egroup`} control sequences as equivalents to
   `{`\c1 and `}`\c2. They can be used instead  of `{`\c1 and~`}`\c2 when we
   need to open/close a group, to create a math list, or when a box is constructed.
   For example, \z`\hbox\bgroup<text>\egroup` is syntactically correct.
@@ -1951,6 +1977,12 @@ If it is~a~Lua\TeX/ only command then three *** are prefixed.
   the given `<step>`.
   To activate this feature you must set the \x`\pdfadjustspacing`
   numeric register to a positive value. 
+* \i efcode `\efcode <font selector><char. code>=<number>`
+  sets the degree of willigness of given character to be deformed when
+  `\pdffontexpand` is used. Default value for all
+  characters is 1000 and `<number>`/1000 gives the proportion coefficient for
+  stretching or shrinking of the character with respect to the \"normal" deformation
+  of characters with default value 1000.
 * \i rpcode \i lpcode 
   `\rpcode <font selector><char. code>=<number>`,
   `\lpcode <font selector><char. code>=<number>` allows the declaration of
@@ -2044,7 +2076,7 @@ If it is~a~Lua\TeX/ only command then three *** are prefixed.
   for the following box in
   the current vertical list. This box is appended immediately after
   the previous box. 
-  \x`\offinterlineskip` ignores the \x`\baselineskip` rule for all following
+  {\noda\x`\offinterlineskip`} ignores the \x`\baselineskip` rule for all following
   boxes until the current group is closed. 
 * All vertical glues at the top of the page inserted by \x`\vskip` are
   ignored. Macro \x`\vglue` behaves like the `\vskip` primitive command but its glue
@@ -2204,7 +2236,7 @@ If it is~a~Lua\TeX/ only command then three *** are prefixed.
 
 \vfil\break
 
-\nonum\sec Index
+\nonum\sec[index] Index
 
 \iis LaTeX/macros {\LaTeX/ macros}
 \iis plain~TeX/macros {plain \TeX/ macros}
@@ -2236,7 +2268,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.6 (\the\year-\thed\month-\thed\day)
+Version of the text: 0.7 (\the\year-\thed\month-\thed\day)
 
 \break