texlive[73917] Master/texmf-dist/doc/pdftex/manual: pdftex manual
commits+karl at tug.org
commits+karl at tug.org
Wed Feb 12 16:47:03 CET 2025
Revision: 73917
https://tug.org/svn/texlive?view=revision&revision=73917
Author: karl
Date: 2025-02-12 16:47:03 +0100 (Wed, 12 Feb 2025)
Log Message:
-----------
pdftex manual update for TL25
Modified Paths:
--------------
trunk/Master/texmf-dist/doc/pdftex/manual/ChangeLog
trunk/Master/texmf-dist/doc/pdftex/manual/incl/pdftex-help.txt
trunk/Master/texmf-dist/doc/pdftex/manual/incl/pdftex-syntax.tex
trunk/Master/texmf-dist/doc/pdftex/manual/pdftex-a.pdf
trunk/Master/texmf-dist/doc/pdftex/manual/pdftex.tex
Modified: trunk/Master/texmf-dist/doc/pdftex/manual/ChangeLog
===================================================================
--- trunk/Master/texmf-dist/doc/pdftex/manual/ChangeLog 2025-02-12 14:58:30 UTC (rev 73916)
+++ trunk/Master/texmf-dist/doc/pdftex/manual/ChangeLog 2025-02-12 15:47:03 UTC (rev 73917)
@@ -1,3 +1,21 @@
+2025-01-25 Karl Berry <karl at freefriends.org>
+
+ * pdftex.tex (\ignoreprimitiveerror): document this.
+
+2025-01-18 Karl Berry <karl at freefriends.org>
+
+ * pdftex.tex (\pdfximage): mention that image metadata is (now)
+ ignored if it's bogus.
+
+2024-08-20 Karl Berry <karl at freefriends.org>
+
+ * pdftex.tex (\pdfstartlink): give complete url example.
+ (thoughout): use whatsit
+
+2024-07-21 Karl Berry <karl at freefriends.org>
+
+ * pdftex.tex (\pdfuseptexuseunderscore): new section.
+
2024-02-22 Max Chernoff <karl at freefriends.org>
* pdftex.tex (\pdfximage): mentioned named destination
Modified: trunk/Master/texmf-dist/doc/pdftex/manual/incl/pdftex-help.txt
===================================================================
--- trunk/Master/texmf-dist/doc/pdftex/manual/incl/pdftex-help.txt 2025-02-12 14:58:30 UTC (rev 73916)
+++ trunk/Master/texmf-dist/doc/pdftex/manual/incl/pdftex-help.txt 2025-02-12 15:47:03 UTC (rev 73917)
@@ -61,9 +61,9 @@
-pdfTeX 3.141592653-2.6-1.40.25 (TeX Live 2023)
-kpathsea version 6.3.5
-Copyright 2023 Han The Thanh (pdfTeX) et al.
+pdfTeX 3.141592653-2.6-1.40.27 (TeX Live 2025)
+kpathsea version 6.4.1
+Copyright 2025 Han The Thanh (pdfTeX) et al.
There is NO warranty. Redistribution of this software is
covered by the terms of both the pdfTeX copyright and
the Lesser GNU General Public License.
@@ -70,6 +70,6 @@
For more information about these matters, see the file
named COPYING and the pdfTeX source.
Primary author of pdfTeX: Han The Thanh (pdfTeX) et al.
-Compiled with libpng 1.6.39; using libpng 1.6.39
-Compiled with zlib 1.2.13; using zlib 1.2.13
+Compiled with libpng 1.6.46; using libpng 1.6.46
+Compiled with zlib 1.3.1; using zlib 1.3.1
Compiled with xpdf version 4.04
Modified: trunk/Master/texmf-dist/doc/pdftex/manual/incl/pdftex-syntax.tex
===================================================================
--- trunk/Master/texmf-dist/doc/pdftex/manual/incl/pdftex-syntax.tex 2025-02-12 14:58:30 UTC (rev 73916)
+++ trunk/Master/texmf-dist/doc/pdftex/manual/incl/pdftex-syntax.tex 2025-02-12 15:47:03 UTC (rev 73917)
@@ -10,6 +10,10 @@
}
\Syntax{
+\cs{ignoreprimitiveerror} \Whatever{integer}
+}
+
+\Syntax{
\cs{knaccode} \Something{font} \Something{8-bit number} \Whatever{integer}
}
@@ -162,6 +166,10 @@
}
\Syntax{
+\cs{pdfuseptexunderscore} \Whatever{integer}
+}
+
+\Syntax{
\cs{rpcode} \Something{font} \Something{8-bit number} \Whatever{integer}
}
Modified: trunk/Master/texmf-dist/doc/pdftex/manual/pdftex-a.pdf
===================================================================
(Binary files differ)
Modified: trunk/Master/texmf-dist/doc/pdftex/manual/pdftex.tex
===================================================================
--- trunk/Master/texmf-dist/doc/pdftex/manual/pdftex.tex 2025-02-12 14:58:30 UTC (rev 73916)
+++ trunk/Master/texmf-dist/doc/pdftex/manual/pdftex.tex 2025-02-12 15:47:03 UTC (rev 73917)
@@ -10,7 +10,7 @@
%
%\DocumentMetadata{testphase={phase-III,table}}
\documentclass{pdftexmanual}
-\svnscan $Id: pdftex.tex 924 2024-02-23 02:20:18Z karl $
+\svnscan $Id: pdftex.tex 946 2025-01-25 17:23:55Z karl $
%
\title{The pdf\TeX\ user manual}
@@ -92,7 +92,7 @@
\section{Legal notice}
-Copyright \copyright\ 1996--2024 \THANH.
+Copyright \copyright\ 1996--2025 \THANH.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2
or any later version published by the Free Software Foundation;
@@ -749,17 +749,16 @@
echo "times TimesNewRomanPSMT <8r.enc <times.ttf" >>test.map
\end{verbatim}
-There are a limitations with TrueType fonts in comparison with
-Type~1 fonts:
+TrueType fonts have some limitations in comparison with Type~1 fonts:
\begin{itemize}
-\item The special effects SlantFont\slash ExtendFont did not work
- before version 1.40.0.
\item To subset a TrueType font, the font must be specified as re\hyph
encoded, therefore an encoding vector must be given.
\item TrueType fonts used in embedded \PDF\ files are kept
untouched; they are not replaced or merged with the same font
used in the document, as happens with Type~1.
+\item The special effects SlantFont\slash ExtendFont did not work
+ before version 1.40.0.
\end{itemize}
For much more about \PDFTEX\ and TrueType fonts, including many details
@@ -1020,7 +1019,7 @@
\type{/Producer} (defaults to \hbox{\tt pdfTeX-\currentpdftex}),\newline
\type{/Creator} (defaults to \type{TeX}),\newline
\type{/CreationDate} (defaults to current date and time, with time zone),\newline
-\type{/ModDate} (same default),\newline
+\type{/ModDate} (same default as \type{/CreationDate}),\newline
\type{/Trapped} (defaults to \type{/False},\newline
\type{/PTEX.Fullbanner} (defaults to the \cs{pdftexbanner} string, q.v.).
@@ -1157,6 +1156,21 @@
omitted entirely. Example: \verb|\pdftrailerid{}|. This can be useful
in making reproducible \PDF{}s. \introduced{1.40.17}
+\subsection{\cs{pdfuseptexunderscore}}
+\pdftexprimitive{\Syntax{\cs{pdfuseptexunderscore} \Whatever{integer}}}
+
+If this parameter is zero, and \cs{pdfmajorversion} is $<2$, use
+`\type{/PTEX.} as the prefix for the relevant \type{/Info} keys, as was
+done through 2024. If this parameter is $>0$, or \cs{pdfmajorversion} is
+$\ge2$, use `\type{PTEX_}', with underscore instead of period. For
+example, if \cs{pdfmajorversion=2}, the key \type{/PTEX_Fullbanner} will
+be defined instead of \type{/PTEX.Fullbanner}.
+
+Using \type{_} is required by updates to the PDF 32000-2-2020 standard,
+and/or by validators; for backwards compatibility, PDF 1.x output still
+uses \type{.}\ by default.
+\introduced{1.40.27}
+
\section{Fonts}
\subsection{\cs{pdfadjustspacing}}
@@ -1563,7 +1577,7 @@
\pdftexprimitive{\Syntax{\cs{pdfinterwordspaceoff}}}
\pdftexprimitive{\Syntax{\cs{pdfspacefont} \Something{general text}}}
-The first two commands insert corresponding whatsit nodes which turn
+The first two commands insert corresponding whatsit items which turn
on/off generation of faked interword spaces in the \PDF\ output (they
cause errors in \DVI\ output). This allows for better reflowing of text
on the fly by \PDF\ readers, better extraction of textual content, and
@@ -2031,10 +2045,10 @@
\pdftexprimitive{\Syntax{\cs{pdfrefobj} \Something{object number}
\Modelist{h, v, m}}}
-This command appends a whatsit node to the list being built. When the whatsit
-node is searched at shipout time, \PDFTEX\ will write the object
-\Something{object number}
-to the \PDF\ output if it has not been written yet.
+This command appends a whatsit item to the list being built. When the
+whatsit is searched at shipout time, \PDFTEX\ will write the object
+\Something{object number} to the \PDF\ output if it has not been written
+yet.
\subsection{\cs{pdfretval}}
\pdftexprimitive{\Syntax{\cs{pdfretval} \Whatever{read-only integer}}}
@@ -2159,8 +2173,8 @@
appended to the list being built. The number of the most recently created
form XObject is accessible via \cs{pdflastxform}.
-When issued, \cs{pdfrefxform} appends a whatsit node to the list being
-built. When the whatsit node is searched at shipout time, \PDFTEX\ will
+When issued, \cs{pdfrefxform} appends a whatsit item to the list being
+built. When the whatsit item is searched at shipout time, \PDFTEX\ will
write the form \Something{object number} to the \PDF\ output if it is
not written yet.
@@ -2219,20 +2233,25 @@
specified values. If some (but not all) are given, the rest will be set
to a value corresponding to the remaining ones so as to make the image
size to yield the same proportion of $width : (height+depth)$ as the
-original image size, where depth is treated as zero. If none are given
-then the image will have its natural size.
+original image size, where depth is treated as zero. If no
+\Something{rule spec} is given then the image will have its natural
+size.
An image inserted at its natural size often has a resolution of
\type{\pdfimageresolution} (see below) given in dots per inch in the
-output file, but some images may contain data specifying the image
-resolution, and in such a case the image will be scaled accordingly. The
-dimensions of an image can be accessed by putting the \cs{pdfrefximage}
-command in a box and checking the box's dimensions:
+output file. However, if an image contains metadata specifying the image
+resolution, the image will be scaled accordingly---unless (as of
+\PDFTEX\ 1.40.27, released in 2025) the embedded image metadata is
+patently incorrect, such as 1dpi x 1dpi, in which case \PDFTEX\ ignores
+the metadata and issues a warning. (Otherwise the bogus data would
+typically lead to an arithmetic overflow error from \TEX.)
+The dimensions of an image can be accessed by using the
+\cs{pdfrefximage} command in a box and checking the box's dimensions:
+
\begin{verbatim}
\setbox0=\hbox{\pdfximage{somefile.png}\pdfrefximage\pdflastximage}
\end{verbatim}
-
Now we can use \cs{wd0} and \cs{ht0} to find the natural size of the
image as determined by \PDFTEX.
@@ -2275,8 +2294,8 @@
\subsection{\cs{pdfrefximage}}
\pdftexprimitive{\Syntax{\cs{pdfrefximage} \Something{object number}}}
-\cs{pdfrefximage} appends a whatsit node to the list being built. When
-the whatsit node is searched at shipout time, \PDFTEX\ will write the image
+\cs{pdfrefximage} appends a whatsit item to the list being built. When
+the whatsit item is searched at shipout time, \PDFTEX\ will write the image
with number \Something{object number} to the \PDF\ output if it has not been
written yet.
@@ -2539,14 +2558,15 @@
\pdftexprimitive{\Syntax{\cs{pdfannot} \Something{annot type spec}
\Modelist{h, v, m}}}
-This command appends a whatsit node corresponding to an annotation to
+\label{pdfannot}
+This command appends a whatsit item corresponding to an annotation to
the list being built. The dimensions of the annotation can be controlled
via the \Something{rule spec}. The default values are ``running'' for
all width, height and depth. When an annotation is written out, running
dimensions will take the corresponding values from the box containing
-the whatsit node representing the annotation. The \Something{general
+the whatsit item representing the annotation. The \Something{general
text} is inserted as raw \PDF\ code to the contents of annotation. The
-annotation is written only if the corresponding whatsit node is searched
+annotation is written only if the corresponding whatsit item is searched
at shipout time.
\subsection{\cs{pdflastannot}}
@@ -2570,7 +2590,7 @@
\pdftexprimitive{\Syntax{\cs{pdfdest} \Something{dest spec}
\Modelist{h, v, m}}}
-This primitive appends a whatsit node which establishes a destination
+This primitive appends a whatsit item which establishes a destination
for links and bookmark outlines; the link is identified by either a
number or a symbolic name, and the way the viewer is to display the page
is specified in \Something{dest spec}, which must be one of those
@@ -2607,7 +2627,7 @@
a separate namespace and therefore may have the same identifiers as a
regular destination.
-The destination is written out only if the corresponding whatsit node is
+The destination is written out only if the corresponding whatsit item is
searched at shipout time.
\subsection{\cs{pdfstartlink}}
@@ -2618,42 +2638,77 @@
\Modelist{h, m}
}}
-This primitive is used along with \cs{pdfendlink} and appends
-a whatsit node corresponding to the start of a hyperlink. The whatsit
-node representing the end of the hyperlink is created by
-\cs{pdfendlink}. The dimensions of the link are handled in the
-similar way as in \cs{pdfannot}. Both \cs{pdfstartlink} and
-\cs{pdfendlink} must be in the same level of box nesting. A hyperlink
-with running width can be multi\hyph line or even multi\hyph page, in which case
-all horizontal boxes with the same nesting level as the boxes containing
-\cs{pdfstartlink} and \cs{pdfendlink} will be treated as part of
-the hyperlink. The hyperlink is written out only if the corresponding
-whatsit node is searched at shipout time.
+\noindent \Syntax{
+\Something{attr spec} \Means
+ \Literal{attr} \Something{general text}
+}
+\noindent \Syntax{
+\Something{action spec} \Means
+ \Literal{user} \Something{user-action spec}
+ \Or \Literal{goto} \Something{goto-action spec}
+ \Or \Literal{thread} \Something{thread-action spec}
+}
-Additional attributes, which are explained in great detail in the
-\PDFReference, can be given via \Something{attr spec}. Typically, the
-attributes specify the color and thickness of any border around the
-link. As a simple example, \verb|/C [0.9 0 0] /Border [0 0 2]| specifies
-a color (in \RGB) of dark red, and a border thickness of 2~points.
+This primitive is used along with \cs{pdfendlink} and appends a whatsit
+item corresponding to the start of a hyperlink. Another whatsit
+representing the end of the hyperlink is created by \cs{pdfendlink}.
+Some salient points about PDF links:
-While all graphics and text in a \PDF\ document have relative positions,
+\begin{itemize}
+\item The dimensions of the link are handled in the similar way as in
+\cs{pdfannot} (p.~\pageref{pdfannot}).
+
+\item A \cs{pdfstartlink} and its corresponding \cs{pdfendlink} must be
+at the same level of box nesting.
+
+\item The hyperlink is written to the final output only if the
+corresponding whatsit is searched at shipout time.
+
+\item A hyperlink with running width can be multi\hyph line or even multi\hyph
+page, in which case all horizontal boxes with the same nesting level as
+the boxes containing \cs{pdfstartlink} and \cs{pdfendlink} will be
+treated as part of the hyperlink.
+
+\item While all graphics and text in a \PDF\ document have relative positions,
annotations have internally hard\hyph coded absolute positions. Again
this is for the sake of speed optimization. The main disadvantage is
that these annotations do \emph{not} obey transformations issued by
\type{\pdfliteral}.
+\end{itemize}
+
+The \Something{attr spec} allows specifying numerous additional
+attributes for the link, which are explained in great detail in the
+\PDFReference. Typically, the attributes specify the color and thickness
+of any border around the link. As a simple example,
+\verb|attr{/C [0.9 0 0] /Border [0 0 2]}|
+specifies a color (in \RGB) of dark red, and a border thickness of 2
+(PostScript) points.
+
The \Something{action spec} specifies the action that should be
-performed when the hyperlink is activated, one of (see the syntax
-rules): \Literal{user} \Something{user-action spec},
-\Literal{goto} \Something{goto-action spec},
-\Literal{thread} \Something{thread-action spec}.
+performed when the hyperlink is activated. The data inside the
+\Something{action spec}s is typically PostScript dictionaries and
+variable settings, as defined by the \PDFReference. The different
+\Something{action spec} possibilities are:
\begin{itemize}
\item A \Something{user-action spec} (\type{user{...}}) performs a
-user\hyph defined action. Examples:
-a \URL, as in \verb|/S /URI /URI (https://tug.org/)|;
-a named action, as in \verb|/S /Named /N /NextPage|.
+user\hyph defined action, such as jumping to another
+location in the document or opening a url (see the ``Actions'' section
+in the \PDFReference, \S12.6). Here's a complete example for making a
+link to a url:
+\begin{verbatim}
+\pdfstartlink
+ attr{/Border [0 0 0]}
+ user{/Subtype /Link
+ /A << /S /URI /URI (https://tug.org/) >>}%
+TUG home page%
+\pdfendlink
+\end{verbatim}
+\noindent The \type{/Border} value in the \type{attr} line eliminates
+the default box around the link displayed by viewers.
+
\item A \Something{goto-action spec} (\type{goto...}) performs various
goto actions, and is by far the most complex action. Here is a copy of
the syntax, for easier reference:
@@ -2744,7 +2799,7 @@
\pdftexprimitive{\Syntax{\cs{pdfrunninglinkoff}}}
\pdftexprimitive{\Syntax{\cs{pdfrunninglinkon}}}
-These commands create corresponding whatsit nodes which turn off/on
+These commands create corresponding whatsit items 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.
@@ -2756,7 +2811,7 @@
top entry in \type{pdf_link_stack}; if so, that box would become a link,
too.
-The whatsit nodes created by the above primitives turn off/on a flag
+The whatsit items 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.
@@ -2846,14 +2901,14 @@
}}
Analogous to \cs{special} in the original \TEX, this command inserts
-raw \PDF\ code into the output, appending a whatsit node to the list
+raw \PDF\ code into the output, appending a whatsit item to the list
being built. This allows support of color and text transformation, among
other things.
By default, \Something{general text} is expanded immediately, when the
-whatsit node is created, as with \cs{special}. Starting with \PDFTEX\
+whatsit item is created, as with \cs{special}. Starting with \PDFTEX\
1.40.25, the optional keyword \Literal{shipout} can be used to delay
-expansion of \Something{general text} until the whatsit node is shipped
+expansion of \Something{general text} until the whatsit item is shipped
out, as with non-\cs{immediate} \cs{write}.
Normally, \PDFTEX\ ends a text section in the \PDF\ output and sets the
@@ -3226,7 +3281,7 @@
\section{Macro programming}
-Expansion-related commands.
+Expansion and other programming-related commands.
\subsection{\cs{expanded}}
\pdftexprimitive{\Syntax{\cs{expanded} \Something{tokens}
@@ -3252,6 +3307,30 @@
(redefined, made \cs{undefined}, has never been primitive), it is false.
\introduced{1.40.0}
+\subsection{\cs{ignoreprimitiveerror}}
+\pdftexprimitive{\Syntax{\cs{ignoreprimitiveerror} \Whatever{integer}}}
+
+If this primitive parameter is set to~1, the error\\
+\verb|! Infinite glue shrinkage found in box being split|\\
+is changed from an error to a warning, and thus the exit status is not
+changed to failure.
+
+Other values of \cs{ignoreprimitiveerror} are reserved for future use.
+
+Here is a simple plain \TeX\ example to provoke that error:
+
+\begin{verbatim}
+\ignoreprimitiveerror=1 % with this, get warning
+\setbox0=\vbox{\hrule height 1pt \vskip 0pt minus 1fill}
+\setbox1=\vsplit0 to 5pt
+\end
+\end{verbatim}
+
+This parameter is defined only when the \type{-etex} option is given,
+like the standard \ETEX\ extensions, which is the default configuration.
+
+\introduced{1.40.27}
+
\subsection{\cs{partokencontext}}
\pdftexprimitive{\Syntax{\cs{partokencontext} \Something{number}}}
@@ -4193,7 +4272,7 @@
\Something{action spec} \Means
\Literal{user} \Something{user-action spec}
\Or \Literal{goto} \Something{goto-action spec}
- \Or \Next \Literal{thread} \Something{thread-action spec}
+ \Or \Literal{thread} \Something{thread-action spec}
}
\Syntax{
More information about the tex-live-commits
mailing list.