pdftex manual update for 2021

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

6 files changed, 248 insertions, 75 deletions

diff --git a/Master/texmf-dist/doc/pdftex/manual/ChangeLog b/Master/texmf-dist/doc/pdftex/manual/ChangeLog
index 307eb5ea5f1..8d85229fc3b 100644
--- a/Master/texmf-dist/doc/pdftex/manual/ChangeLog
+++ b/Master/texmf-dist/doc/pdftex/manual/ChangeLog
@@ -1,3 +1,23 @@
+2021-02-18  Karl Berry  <karl@freefriends.org>
+
+	* pdftex-t.tex: update for 2021:
+	(\tracinglostchars): new behavior when >=3.
+	(\tracingstacklevels): new primitive.
+
+2020-06-14  Karl Berry  <karl@freefriends.org>
+
+	* pdftex-t.tex: small tweaks throughout.
+	
+	(\pdffontexpand): warn about pdftex immediately loading the
+	non-autoexpanded fonts at maximum stretch and shrink, even if
+	they never used. Report from Robert Schlict,
+	https://tug.org/pipermail/tex-live/2020-March/045099.html
+	https://mailman.ntg.nl/pipermail/ntg-pdftex/2020-March/004307.html.
+
+	(\pdfgentounicode): mention the automapping of uniXXXX.
+	Suggestion by Ulrike Fischer,
+	https://tug.org/pipermail/tex-live/2020-May/045763.html
+
 2020-03-02  Karl Berry  <karl@freefriends.org>
 
 	* Makefile (common_deps): don't include pdftex-help.txt,
diff --git a/Master/texmf-dist/doc/pdftex/manual/Makefile b/Master/texmf-dist/doc/pdftex/manual/Makefile
index 7c1e369adaa..05c57fc29a5 100644
--- a/Master/texmf-dist/doc/pdftex/manual/Makefile
+++ b/Master/texmf-dist/doc/pdftex/manual/Makefile
@@ -1,4 +1,4 @@
-# $Id: Makefile 822 2020-03-02 16:57:37Z karl $
+# $Id: Makefile 848 2021-02-18 17:49:17Z karl $
 # Makefile for pdfTeX documentation.  Public domain.
 
 # Get version we're documenting from the \def in the manual.
@@ -52,11 +52,15 @@ pdftex-w.txt: pdftex-w.pdf
 	| expand >$@ || rm -f $@
 	wc -l pdftex-w.txt  # set titlepagelines=half of this
 
-# PDF for the title page.
+# PDF for the title page. This should be updated every year;
+# - update version numbers
+# - make new binary
+# - run this target
+# Also check pdftex-help.txt for updates.
 pdftex_binary = ../../source/build-pdftex/texk/web2c/pdftex
 pdftex-w.pdf: pdftex-w.tex Makefile
 	TEXFONTS=/usr/local/texlive/dev/texmf-dist/fonts// \
-	$(pdftex_binary) -ini '\nonstopmode\input $<'
+	$(pdftex_binary) -ini '$<'
 
 
 # Too annoying to remake help text every time; check by hand when needed.
diff --git a/Master/texmf-dist/doc/pdftex/manual/pdftex-a.pdf b/Master/texmf-dist/doc/pdftex/manual/pdftex-a.pdf
index 66806dfda35..f5d6372f936 100644
--- a/Master/texmf-dist/doc/pdftex/manual/pdftex-a.pdf
+++ b/Master/texmf-dist/doc/pdftex/manual/pdftex-a.pdf
diff --git a/Master/texmf-dist/doc/pdftex/manual/pdftex-syntax.txt b/Master/texmf-dist/doc/pdftex/manual/pdftex-syntax.txt
index 0d9994e5e0d..7125d653fd0 100644
--- a/Master/texmf-dist/doc/pdftex/manual/pdftex-syntax.txt
+++ b/Master/texmf-dist/doc/pdftex/manual/pdftex-syntax.txt
@@ -46,6 +46,8 @@
 \shbscode <font> <8-bit number>                         (integer)
 \stbscode <font> <8-bit number>                         (integer)
 \tagcode <font> <8-bit number>                          (integer)
+\tracinglostchars                                       (integer)
+\tracingstacklevels                                     (integer)
 
 %% Read-only integers:
 \pdfelapsedtime                                         (read-only integer)
@@ -149,6 +151,8 @@
 \pdfrefximage <object number>
 \pdfresettimer
 \pdfrestore
+\pdfrunninglinkoff
+\pdfrunninglinkon
 \pdfsave
 \pdfsavepos                                             (h, v, m)
 \pdfsetmatrix
diff --git a/Master/texmf-dist/doc/pdftex/manual/pdftex-t.tex b/Master/texmf-dist/doc/pdftex/manual/pdftex-t.tex
index 42c0a11099e..2f323fedce3 100644
--- a/Master/texmf-dist/doc/pdftex/manual/pdftex-t.tex
+++ b/Master/texmf-dist/doc/pdftex/manual/pdftex-t.tex
@@ -1,7 +1,7 @@
 % interface=english modes=letter,screen output=pdftex
 % vim: tw=79
 
-% $Id: pdftex-t.tex 821 2020-03-02 02:14:55Z karl $
+% $Id: pdftex-t.tex 849 2021-02-18 17:55:44Z karl $
 
 % The number of lines on the title page depends on exactly
 % what \PDF\ code is generated.
@@ -38,9 +38,9 @@
     August\or September\or October\or November\or December\else ERROR\fi}
 }
 
-\svnscan $Id: pdftex-t.tex 821 2020-03-02 02:14:55Z karl $
+\svnscan $Id: pdftex-t.tex 849 2021-02-18 17:55:44Z karl $
 
-\def\currentpdftex{1.40.21}
+\def\currentpdftex{1.40.22}
 
 %***********************************************************************
 
@@ -607,7 +607,7 @@
     \font\tenrm=ptmr8r
     \tenrm
     Welcome to pdf\TeX!
-    \bye
+    \end
   \stoptyping
 
 \stopstandardmakeup
@@ -1018,11 +1018,12 @@ needed for building a ready \PDF\ page must be available during the
 graphics files for embedding, and font information (font files,
 encodings).
 
-When \TEX\ builds a page, it places items relative to the top left page
-corner (the \DVI\ reference point). Separate \DVI\ postprocessors allow
-specifying the paper size (\eg\ \quote {A4} or \quote{letter}), so
-that this reference point is moved to the correct position on the paper,
-and the text ends up at the right place.
+When \TEX\ builds a page, it places items relative to the (1in,1in)
+offset from the top left page corner (the \DVI\ reference point).
+Separate \DVI\ postprocessors allow specifying the paper size (\eg\
+\quote {A4} or \quote{letter}), so that this reference point is moved to
+the correct position on the paper, and the text ends up at the right
+place.
 
 In \PDF, the paper dimensions are part of the page definition, and
 \PDFTEX\ therefore requires that they be defined at the beginning of
@@ -1127,10 +1128,11 @@ even without setting any parameters.
   {\getbuffer}
 
 Independent of whether such a configuration file is read or not, the
-first action in a \PDFTEX\ run is that the program reads the global \WEBC\
-configuration file (\filename{texmf.cnf}), which is common to all programs
-in the \WEBC\ system. This file mainly defines file search paths, the
-memory layout (\eg\ string pool and hash size), and other general parameters.
+first action in a \PDFTEX\ run is that the program reads the global
+\WEBC\ configuration file (\filename{texmf.cnf}), which is common to all
+programs in the \WEBC\ system. This file mainly defines file search
+paths, the memory layout (\eg\ string pool and hash size), and a few
+other general parameters.
 
 %***********************************************************************
 
@@ -1190,15 +1192,16 @@ memory layout (\eg\ string pool and hash size), and other general parameters.
   {\getbuffer}
 
 The \PDFTEX\ engine supports building formats for \DVI\ and \PDF\ output
-in the same way as the classical \TEX\ engine does for \DVI.  Format
-generation is enabled by the \type{-ini} option. The default mode (\DVI\
-or \PDF) can be chosen either on the command line by setting the option
-\type{-output-format} to \type{dvi} or \type{pdf}, or by setting the
-\type{\pdfoutput} parameter. The format file then inherits this setting,
-so that a later invocation of \PDFTEX\ with this format starts in the
-preselected mode (which still can be overridden). A format file can be
-read in only by the engine that has generated it; a format incompatible
-with an engine leads to a fatal error.
+in the same way as the classical \TEX\ engine does for \DVI. Format
+generation (and other \type{initex} features) is enabled by the
+\type{-ini} option. The default mode (\DVI\ or \PDF) can be chosen
+either on the command line by setting the option \type{-output-format}
+to \type{dvi} or \type{pdf}, or by setting the \type{\pdfoutput}
+parameter. The format file then inherits this setting, so that a later
+invocation of \PDFTEX\ with this format starts in the preselected mode
+(which still can be overridden). A format file can be read in only by
+the engine that has generated it; a format incompatible with an engine
+leads to a fatal error.
 
 It is customary to package the configuration and macro file input
 into a \type{.ini} file.  \Eg, the file \type{etex.ini} in
@@ -1225,10 +1228,14 @@ pdftex -ini *pdflatex.ini
 
 These calls produce format files \filename{etex.fmt},
 \filename{pdfetex.fmt}, and \filename{pdflatex.fmt}, as the default
-format file name is taken from the input file name. You can overrule
+format file name is taken from the input file name. You can override
 this with the \type{-jobname} option. The asterisk \type{*} before the
-file name is a unusual feature, only in \type{-ini} mode, which causes
-the \PDFTEX\ engine to enable \ETEX\ features.
+file name is an unusual flag, only used in \type{-ini} mode, which
+causes the \PDFTEX\ engine to enable \ETEX's features.
+
+Incidentally, as of \PDFTEX\ 1.40.21 (\TEX\ Live 2020), \filename{.fmt}
+files are compressed with \type{zlib}. This makes for a considerable
+savings in space, and consequently in time.
 
 \subsection{Testing the installation}
 
@@ -1315,10 +1322,10 @@ the object table size is now obsolete and ignored).
 
 \section{Invoking \PDFTEX}
 
-\PDFTEX\ has many command line options.  With the exception of the
-simple and rarely-used \type{-draftmode} and \type{-output-format}
-options, they are all inherited from the common framework for \TeX\
-engines as implemented in \WEBC\ (\from [web2c] has the manual).
+\PDFTEX\ has many command line options. Except for the simple and
+rarely-used \type{-draftmode} and \type{-output-format} options, they
+are all inherited from the common framework for \TeX\ engines as
+implemented in \WEBC\ (its manual is available at \from [web2c]).
 
 The same commonality holds for environment variables; see the section
 ``Setting search paths'' above for an overview.  Two additional
@@ -1341,11 +1348,11 @@ are \type{\year}, \type{\month}, \type{\day}, and \type{\time}. If
 has no effect. If \type{FORCE_SOURCE_DATE} is unset, set to the empty
 string, or set to~\type{0}, the primitives reflect the current time as
 usual. Any other value elicits a warning, and the current time is used.
-(This is useful only if one wants to make reproducible \PDF{}s for a set
+This is useful if one wants to make reproducible \PDF{}s for a set
 of documents without changing them in any way, e.g., an operating system
 distribution with manuals that use \type{\today}. Except in such unusual
 circumstances, it is better not to set this, and let the \TEX\
-primitives retain the meaning they have always had.)
+primitives retain the meaning they have always had.
 
 In addition, if both \type{SOURCE_DATE_EPOCH} and
 \type{FORCE_SOURCE_DATE} are set, \type{\pdffilemoddate} returns a value
@@ -2528,19 +2535,19 @@ will try to scale (shrink) the glyphs in that line using fixed steps,
 until the line fits. When lines are too spacy, the opposite happens:
 \PDFTEX\ starts scaling (stretching) the glyphs until the white space
 gaps is acceptable. This glyph stretching and shrinking is called
-{\em font expansion}. To enable font expansion, don't forget to set
-\type{\pdfadjustspacing} to a value greater than zero.
+{\em font expansion}. To enable font expansion, \type{\pdfadjustspacing}
+must be set to a value greater than zero.
 
 There are two different modes for font expansion:
 
 First, if the \type{autoexpand} option is given --- which is the
 recommended mode --- only a single map entry is needed for all expanded
 font versions, using the name of the unexpanded \TFM\ file ({\em
-tfmname}). No expanded {\em tfmname} versions need to mentioned (they are
-ignored), as \PDFTEX\ generates expanded copies of the unexpanded \TFM\
+tfmname}). No expanded {\em tfmname} versions need be mentioned (they are
+ignored), as \PDFTEX\ generates expanded instances of the unexpanded \TFM\
 data structures and keeps them in its memory. Since \PDFTEX~1.40.0 the
 \type{autoexpand} mode happens within the page stream by modification of
-the text matrix (\PDF\ operator ``\type{Tm}''), and not anymore on font
+the text matrix (\PDF\ operator ``\type{Tm}''), and not at the font
 file level, giving the advantage that it now works not only with Type~1
 but also with TrueType and OpenType fonts (and even without embedding
 a font file; but that's not recommended). In this mode \PDFTEX\ requires
@@ -2552,17 +2559,25 @@ in all required expansion values. The expanded {\em tfmname} variants
 are constructed by adding the font expansion value to the {\em tfmname}
 of the base font, \eg\ there must be a map entry with {\em tfmname}
 \type{sometfm+10} for 1\,\% stretch or \type{sometfm-15} for 1.5\,\%
-shrink. This also means, that for each expanded font variant a \TFM\
+shrink. This also means that for each expanded font variant a \TFM\
 file with properly expanded metrics must exist. Having several map
-entries for the various expansion values of a font requires to provide
+entries for the various expansion values of a font requires providing
 for each expansion value an individually crafted font file with expanded
 glyphs. Depending on how these glyphs are generated, this might give
 slightly better glyph forms than the rather simple glyph stretching
 used in \type{autoexpand mode}. The drawback is that several font
 files will be embedded in the \PDF\ output for each expanded font,
 leading to significantly larger \PDF\ files than in \type{autoexpand}
-mode. For moderate expansion values going without \type{autoexpand}
-mode is not worth the trouble.
+mode. For moderate expansion values, going without \type{autoexpand}
+mode is typically not worth the trouble.
+
+A caveat: when \type{\pdffontexpand} is executed, \PDFTEX\ immediately
+loads two fonts, at the maximum stretch and shrink; in our example,
+\type{sometfm+30} and \type{sometfm-20}. (If they aren't available,
+\type{mktextfm} may be uselessly called, and then an error message
+issued.) This happens even if those fonts never end up being used, which
+is arguably undesirable, but hard to change. It is not a problem when
+using \type{autoexpand}.
 
 The font expansion mechanism is inspired by an optimization first
 introduced by Prof.~Hermann Zapf, which in itself goes back to
@@ -2571,7 +2586,8 @@ glyphs to optimize the grayness of a page. So, there are many, slightly
 different~a's, e's, etc. For practical reasons \PDFTEX\ does not use
 such huge glyph collections; it uses horizontal scaling instead. This is
 sub||optimal, and for many fonts, possibly offensive to the design. But,
-when using \PDF, it's not illogical: \PDF\ viewers use so||called
+when using \PDF, it's not illogical: \PDF\ viewers support arbitrary
+scaling, after all. (Also, they used to use so||called
 Multiple Master fonts when no fonts are embedded and|/|or can be found
 on the target system. Such fonts are designed to adapt their design to
 the different scaling parameters. It is up to the user to determine
@@ -2579,7 +2595,8 @@ to what extent mixing slightly remastered fonts can be used without
 violating the design. Think of an O: when geometrically stretched, the
 vertical part of the glyph becomes thicker, and looks incompatible with
 an unscaled original.  With a Multiple Master situation, one can stretch
-while keeping this thickness compatible.
+while keeping this thickness compatible. Perhaps something similar
+happens with TrueType and OpenType fonts nowadays.)
 
 \pdftexprimitive{\Syntax{\Tex{\pdfadjustspacing} \Whatever{integer}}}
 \bookmark{\tex{pdfadjustspacing}}
@@ -3029,16 +3046,17 @@ including fonts in the output. Such a resource (also called a CMap
 resource) maps glyph names to Unicode characters in a \PDF\ file.
 Lacking such a resource, it is the \PDF\ reader which determines how and
 whether searching in the \PDF\ file works.  In practice, searching for
-basic ASCII characters generally works, but searching for anything
+basic \ASCII\ characters generally works, but searching for anything
 beyond those, including ligatures such as `fi', fails in some versions
-of some PDF browsers (most notably Adobe Reader).
+of some \PDF\ browsers (most notably Adobe Reader).
 
 If \type{\pdfgentounicode} is set to \type{1} when the job ends, the
 \type{/ToUnicode} resource will be included in the output, with mappings
 for Type~1 fonts used in the documents. The mapping is created as
 follows: for each glyph in the font, look for its \type{ToUnicode} value
-in a global hash table.  By default that global hash table is empty;
-entries are added to the table using the following command:
+in a global hash table. By default that global hash table is empty, in
+which case \PDFTEX\ merely emits a warning. Entries are added to the
+table using the following command:
 
 \pdftexprimitive{\Syntax{\Tex{\pdfglyphtounicode} \Something{general text}
   \Something{general text}}}
@@ -3054,9 +3072,15 @@ numeric values denoting characters, separated by spaces. For instance:
 \noindent maps the \type{ff} ligature to a pair of \type{f}'s (whose
 code is \type{U+0066}).
 
-The \type{glyphtounicode.tex} file (distributed with \PDFTEX\ and other
-software) contains thousands of such definitions, covering most common
-glyph names.  So, for practical purposes, one would probably want:
+Once a single \type{\pdfglyphtounicode} definition is made, whether it
+is used or not, another feature comes into play: glyph names of the form
+\type{uniXXXX} or \type{uXXXX} are mapped to the natural \type{U+XXXX}.
+Many fonts use this style of naming.
+
+In addition, the \type{glyphtounicode.tex} file (distributed with
+\PDFTEX\ and other software) contains thousands of such definitions,
+covering most common glyph names. So, for practical purposes, one would
+probably want:
 
 \starttyping
 \input glyphtounicode
@@ -3926,6 +3950,38 @@ and fixing the macros may well not be trivial.  Then seeing the warnings
 on every run is just noise, and can be suppressed by setting this
 parameter to a positive number.  \introduced{1.40.13}
 
+\pdftexprimitive{\Syntax{\Tex{\pdfrunninglinkoff}}}
+\pdftexprimitive{\Syntax{\Tex{\pdfrunninglinkon}}}
+
+These commands create corresponding whatsit nodes which turn off/on
+generation of running links. Their typical usage is to turn off
+generation of running links in the header or footer of a page.
+Generation of running links is on when the shipout routine begins.
+
+The generation of running links works roughly like this: \PDFTEX\ keeps
+a stack of links created by \type{\pdfstartlink}, called
+\type{pdf_link_stack}. When writing out an hbox to \PDF, \PDFTEX\ checks
+if the nesting level of the box is the same as the nesting level of the
+top entry in \type{pdf_link_stack}; if yes that box would become a link,
+too.
+
+The whatsit nodes created by the above primitives turn off/on a flag
+which controls if a hbox being shipped can become a link, in addition to
+the previous condition.
+
+Thus, the commands must be inserted before the hbox in question. For example:
+
+\starttyping
+% (1) good:
+\hbox{\pdfrunninglinkoff
+  \hbox{this is a line that would become a link otherwise}
+}
+
+% (2) bad:
+\hbox{\pdfrunninglinkoff this is a line that would become a link} 
+% too late; \pdfrunninglinkoff must be inserted before the box
+\stoptyping
+
 %***********************************************************************
 
 \subsection{Bookmarks}
@@ -4274,8 +4330,8 @@ example, the first ten bytes of the source of this manual are {\tt
 As of \TEXLIVE\ 2020, the \type{\input} primitive in all \TEX\ engines,
 including \PDFTEX, now also accepts a group-delimited filename argument,
 as a system-dependent extension, as in \type{\input\Lbrace
-foo.tex\Rbrace}. The usage with a standard space/token-delimited
-filename is completely unchanged.
+foo.tex\Rbrace}. The usage of \type{\input} with a standard
+space/token-delimited filename is completely unchanged.
 
 This group-delimited argument was previously implemented in Lua\TEX; now
 it is available in all engines. \ASCII\ double quote characters
@@ -4288,9 +4344,11 @@ primitive, command line option, etc. This is allowed because additional
 methods of recognizing filenames are explicitly mentioned in
 \type{tex.web} as acceptable system-dependent extensions.
 
-Incidentally, this does not currently
-affect \LATEX's \type{\input} command, as that is a macro redefinition
-of the standard \type{\input} primitive. \introduced{1.40.21}
+Incidentally, this does not directly affect \LATEX's \type{\input}
+command, as that is a macro redefinition of the standard \type{\input}
+primitive.
+
+\introduced{1.40.21}
 
 %***********************************************************************
 
@@ -4475,10 +4533,8 @@ in \DVI\ mode.
 \pdftexprimitive{\Syntax{\Tex{\pdfshellescape} \Whatever{read||only integer}}}
 \bookmark{\tex{pdfshellescape}}
 
-This primitive is~1 if \type{\write18} is enabled, 2 if it is
-restricted, and 0 otherwise.  (\type{\write18} was
-\ifnum\pdfshellescape=0\relax not \fi enabled when this manual was
-typeset.)  \introduced{1.30.0}
+This primitive is~1 if \type{\write18} is enabled, 2 if its operation is
+restricted to known-safe programs, and 0 otherwise. \introduced{1.30.0}
 
 
 \pdftexprimitive{\Syntax{\Tex{\pdftexbanner} \Whatever{expandable}}}
@@ -4502,19 +4558,108 @@ this document), it returns the number {\tt \pdftexrevision}.
 \bookmark{\tex{pdftexversion}}
 
 Returns the version of \PDFTEX\ multiplied by 100, \eg\ for \PDFTEX\
-version \expandafter\versplit\the\pdftexversion.\pdftexrevision\ used to
-produce this document, it returns {\tt \number\pdftexversion}.
+version \expandafter\versplit\the\pdftexversion.\pdftexrevision\ (used to
+produce this document), it returns {\tt \number\pdftexversion}.
 
 
 \pdftexprimitive{\Syntax{\Tex{\quitvmode}}}
 \bookmark{\tex{quitvmode}}
 
 The primitive instructs \PDFTEX\ to quit vertical mode and start
-typesetting a paragraph. \type{\quitvmode} has the same effect as
-\type{\leavevmode} definition from \type{plain} macro package. Note
-however, that \type{\leavevmode} may conflict with \type{\everypar}
-tokens list. No such risk while using \type{\quitvmode} instead.
-\introduced{1.21a}
+typesetting a paragraph. Thus, \type{\quitvmode} has the same basic
+effect as the \type{\leavevmode} macro from \type{plain.tex}. However,
+\type{\leavevmode} expands the \type{\everypar} tokens list, which may
+or may not be desired. \type{\quitvmode} does not expand
+\type{\everypar}. \introduced{1.21a}
+
+
+\pdftexprimitive{\Syntax{\Tex{\tracinglostchars} \Whatever{integer}}}
+\bookmark{\tex{tracinglostchars}}
+
+This primitive parameter has always been part of \TEX, and its operation
+with values $\le2$ is unchanged. In addition, if its value is
+$\ge3$, then \quote{Missing character} reports become full errors
+(ordinarily they are only logged), and the character code is reported in
+hex. For example:
+
+\starttyping
+\tracinglostchars=3
+\font\x=logo10 \x \char99 \end
+\stoptyping
+
+will result in this error message:
+\starttyping
+! Missing character: There is no c ("63) in font logo10.
+\stoptyping
+
+(The \type{logo10} font only defines the capital letters used in the
+\METAFONT\ and \METAPOST\ logos, so there is no lowercase.)
+
+This new behavior is essentially the same in all \TeX\ engines except
+the original \TEX\ and \eTeX, where the behavior of
+\type{\tracinglostchars} remains unchanged.
+
+\introduced{1.40.22}
+
+\pdftexprimitive{\Syntax{\Tex{\tracingstacklevels} \Whatever{integer}}}
+\bookmark{\tex{tracingstacklevels}}
+
+If this primitive parameter is $>0$, and \type{\tracingmacros}$\,>0$,
+macro expansion logging is truncated at the specified depth. Also, and
+more importantly, each relevant log line is given a prefix beginning
+with \type{~}, either followed by a \type{.} character for each
+expansion level or only another \type{~} if the expansion was truncated.
+For example:
+
+\starttyping
+\tracingmacros=1      % so macro expansion is logged at all
+\tracingstacklevels=2 % cut off at level 2
+\def\a#1{\relax}      % argument to show parameter logging is affected too
+\def\b#1{\a{#1}}
+\b1
+\stoptyping
+
+\noindent logs the following:
+
+\starttyping
+~.\b #1->\a {#1}
+#1<-1
+~~\a 
+\stoptyping
+
+Thus, the expansion of \type{\b} is logged normally, with the addition
+of the \type{~.} prefix. The expansion of \type{\a} is truncated
+(level~2), hence neither the parameters nor body expansion are shown.
+
+Furthermore, an \type{\input} file counts as an expansion level, and the
+input filename is logged. So, if we add this to our example above:
+\starttyping
+\input anotherfile
+\stoptyping
+
+where \type{anotherfile.tex} simply contains \type{\b2}, the log will
+get:
+
+\starttyping
+~.INPUT anotherfile.tex
+~~\b 
+~~\a 
+\stoptyping
+
+Now the \type{\b} expansion is not logged either, since the expansion
+depth is higher than the \type{\tracingstacklevels} value.
+
+The intended use of \type{\tracingstacklevels} is not so much to
+truncate logging as to indicate the expansion levels for detailed
+debugging. Thus normally it would be set to a large number
+(\type{\maxdimen}, say), so that everything is fully logged, with the
+addition of the expansion level indication with the number of dots in
+the prefix.
+
+The behavior is the same in all \TeX\ engines except the original \TEX\
+and \eTeX, where \type{\tracingstacklevels} remains undefined.
+
+\introduced{1.40.22}
 
 
 \pdftexprimitive{\Syntax{\Tex{\vadjust}
@@ -4529,7 +4674,7 @@ The \type{\vadjust} implementation of \PDFTEX\ adds an optional
 qualifier \Something{pre spec}, which is simply the string \type{pre}, to
 the original \TEX\ primitive with the same name. If
 no \type{pre} is given, \type{\vadjust} behaves exactly as the original
-(see the \TEX book, p.~281): it appends an adjustment item created
+(see {\em The \TEX book}, p.~281): it appends an adjustment item created
 from \Something{vertical mode material} to the current list {\em after}
 the line in which \type{\vadjust} appears. However, with the qualifier
 \type{pre}, the adjustment item is put {\em before} the line in which
@@ -4923,19 +5068,19 @@ drawing editor, and that is suitable for input to text formatters or
 for automatic translation to a variety of formats suitable for input
 to text formatters. A copy made in an otherwise Transparent file
 format whose markup, or absence of markup, has been arranged to thwart
-or discourage subsequent modification by \PDF\ viewers is not Transparent.
+or discourage subsequent modification by PDF viewers is not Transparent.
 An image format is not Transparent if used for any substantial amount
 of text. A copy that is not ``Transparent'' is called {\bf ``Opaque''}.
 
 Examples of suitable formats for Transparent copies include plain
 ASCII without markup, Texinfo input format, LaTeX input format, SGML
 or XML using a publicly available DTD, and standard-conforming simple
-HTML, \POSTSCRIPT\ or \PDF\ designed for human modification.  Examples of
+HTML, \POSTSCRIPT\ or PDF designed for human modification.  Examples of
 transparent image formats include PNG, XCF and JPG.  Opaque formats
 include proprietary formats that can be read and edited only by
 proprietary word processors, SGML or XML for which the DTD and/or
 processing tools are not generally available, and the
-machine-generated HTML, \POSTSCRIPT\ or \PDF\ produced by some word
+machine-generated HTML, \POSTSCRIPT\ or PDF produced by some word
 processors for output purposes only.
 
 The {\bf ''Title Page''} means, for a printed book, the title page itself,
diff --git a/Master/texmf-dist/doc/pdftex/manual/pdftex-w.tex b/Master/texmf-dist/doc/pdftex/manual/pdftex-w.tex
index adc1bef7713..a32da4e54ce 100644
--- a/Master/texmf-dist/doc/pdftex/manual/pdftex-w.tex
+++ b/Master/texmf-dist/doc/pdftex/manual/pdftex-w.tex
@@ -1,13 +1,13 @@
-% $Id: pdftex-w.tex 822 2020-03-02 16:57:37Z karl $
+% $Id: pdftex-w.tex 849 2021-02-18 17:55:44Z karl $
 % run with -ini:
   \catcode`{=1 \catcode`}=2
   \def\TeX{T\kern-.1667em\lower.5ex\hbox{E}\kern-.125emX}
-  \hsize=6.5in \vsize=9in
+  \hsize=6.5in \vsize=9in \parfillskip=0pt plus1fil
 \pdfoutput=1
 \pdfcompresslevel=0
 \pdfobjcompresslevel=0
 \pdfmapline{ptmr8r Times-Roman 2 <8r.enc}
 \font\tenrm=ptmr8r
 \tenrm
-Welcome to pdf\TeX!\hfil
+Welcome to pdf\TeX!\par
 \end