Debian Codegraph @

texmf-dist/doc/pdftex/manual/pdftex.tex

raw
1 % pdfTeX manual, rewritten in LaTeX from the ConTeXt original,
2 % Karl Berry, 2023. Content not significantly changed.
3 % Released under the GFDL v1.2+, same as the ConTeXt version.
4 %
5 % Not quite tagging-ready, numerous warnings like:
6 % Package tagpdf Warning: The structure Sect can not be closed.
7 % and ends with:
8 % ./pdftex.tex:4336: Package tagpdf Error: The number of automatic begin
9 % (1351) and end (1352) ...
10 %
11 %\DocumentMetadata{testphase={phase-III,table}}
12 \documentclass{pdftexmanual}
13 \svnscan $Id: pdftex.tex 979 2026-02-16 15:32:58Z karl $
14
15 %
16 \title{The pdf\TeX\ user manual}
17 \author{\THANH\ and others}
18 \date{\PDFTEX\ \currentpdftex\\
19 \hspace*{1em}\\ \today\\
20 \hspace*{1em}\\ \url{https://pdftex.org}
21 }
22
23 \begin{document}
24 \hypersetup{pageanchor=false} % avoid hyperref duplicate page.1 warning
25 \maketitle
26 \hypersetup{pageanchor=true} % https://tex.stackexchange.com/questions/18924
27 \setcounter{page}{2}
28
29 \tableofcontents
30
31 \chapter{Introduction}
32
33 The main purpose of the \PDFTEX\ project is to create and maintain an
34 extension of \TEX\ that can produce \PDF\ output directly from \TEX\
35 source files and improve\slash enhance the result of \TEX\ typesetting
36 with the help of \PDF\ output. When \PDF\ output is not selected,
37 \PDFTEX\ produces standard \DVI\ output. An important aspect of the
38 project is to investigate alternative justification algorithms; notably,
39 the margin kerning and font expansion algorithms following the \HZ\
40 micro\hyph typography algorithm by Prof.~Hermann Zapf.
41
42 \PDFTEX\ is maintained by \THANH, the original author, and others. The
43 \PDFTEX\ home page is \useurl{ptexorg}. Please send bug reports,
44 suggestions, etc., to the mailing list (\useurl{ptexbugs}).
45
46 \PDFTEX\ is based on the original \TEX\ sources and \WEBC, and has been
47 successfully compiled on \UNIX, \WIN\ and many other systems. It is
48 actively maintained, with great care taken to keep new \PDFTEX\ versions
49 backward\hyph compatible with earlier ones.
50
51 A conservative successor to \TEX, named \ETEX, was developed in the
52 1990s. Since \PDFTEX\ version 1.40, the \ETEX\ extensions are compiled
53 as part of the \PDFTEX\ engine and thus always available. For
54 documentation on the \ETEX\ extensions, see \useurl{etexctan}.
55
56 Furthermore, \PDFTEX\ itself has acquired plenty of extensions over the
57 years which are not related specifically to \PDF\ output, generally new
58 primitives for various features that are inconvenient or impossible to
59 implement at the \TEX\ level. Many of these extensions have been adopted
60 across all engines (sometimes with different primitive names or variant
61 functionality), and some are required by \LATEX. Therefore, in most
62 distributions \type{etex} is a link to \type{pdftex}; the difference
63 being whether \DVI\ or \PDF\ output is generated by default.
64
65 Other extensions are \MLTEX\ and \ENCTEX; these are also included in the
66 \PDFTEX\ implementation, although they are rarely used for new documents.
67
68 \PDFTEX\ does not natively support \UTFEIGHT\ input text,
69 Unicode-encoded fonts, or anything else related to Unicode, as it was
70 written long before Unicode became widespread. Making those changes to
71 the engine now would necessarily create unacceptable incompatibilities,
72 so there are no plans to do so. Thus, when using \PDFTEX, \LaTeX\ and
73 other formats handle \UTFEIGHT\ (and other) input at the \TEX\ macro
74 level, which works well enough in practice for most documents. It is
75 also possible to use TrueType and OpenType fonts with \PDFTEX, if you
76 choose an 8-bit subset to be encoded.
77
78 If you need a \TeX\ engine with native support for Unicode input,
79 TrueType fonts, OpenType fonts, please look into \LUATEX\
80 (\useurl{luatex}) or \XETEX\ (\useurl{xetex}).
81
82 \section{About this manual}
83
84 This manual revision (\rcsrevision) covers \PDFTEX\ development up to
85 version \currentpdftex. The primary repository for both the manual and
86 the \PDFTEX\ sources is \useurl{ptexdevel}. The typeset manual in \PDF\
87 format can be found on \CTAN\ in \useurl{ptexctan}.
88
89 Thanks to the many people who have contributed to the manual.
90 Improvements are always possible, and bugs not unlikely.
91 Please send questions or suggestions via email at \useurl{ptexbugs}.
92
93 \section{Legal notice}
94
95 Copyright \copyright\ 1996--2025 \THANH.
96 Permission is granted to copy, distribute and/or modify this document
97 under the terms of the GNU Free Documentation License, Version 1.2
98 or any later version published by the Free Software Foundation;
99 with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
100 A copy of the license is included in the section entitled ``GNU
101 Free Documentation License''.
102
103 \section{About \PDF}
104
105 Let's start with a very brief introduction to \PDF\ format. For our
106 example, the bit of \TeX\ source below (figure~\ref{fig.titlesource})
107 generates the nearly-minimal \PDF\ file shown on the next page
108 (figure~\ref{fig.titleout}). Since compression is disabled, such a
109 \PDF\ file is rather verbose and readable. The first line
110 (\texttt{\%PDF-1.4}) specifies the \PDF\ version used. \PDF\ viewers are
111 supposed to silently skip over all elements they cannot handle.
112
113 \begin{figure}[b]
114 \bigskip
115 \hrule
116 \medskip
117 \begin{verbatim}
118 \pdfoutput=1
119 \pdfcompresslevel=0
120 \pdfobjcompresslevel=0
121 \pdfmapline{ptmr8r Times-Roman 2 <8r.enc}
122 \font\tenrm=ptmr8r
123 \tenrm
124 Welcome to pdf\TeX!
125 \end
126 \end{verbatim}
127 \vspace{-\baselineskip}
128 \caption{This plain \TeX\ source generates \PDF\ output shown in
129 figure~\ref{fig.titleout}.}
130 \label{fig.titlesource}
131 \end{figure}
132
133 \begin{figure}[p]
134 % Why isn't \vsize enough?
135 \includegraphics[height=1.27\vsize,alt={small PDF file}]
136 {incl/pdfmin-crop.pdf}
137 \caption{The \PDF\ output for the \TeX\ source in figure~\ref{fig.titlesource}.}
138 \label{fig.titleout}
139 \end{figure}
140
141 A \PDF\ file consists of objects. These objects can be recognized by their
142 number and keywords. For example, over in the second column, we can see
143 (modulo editorial line breaks):
144
145 \begin{verbatim}
146 9 0 obj << /Type /Catalog /Pages 5 0 R >> endobj
147 \end{verbatim}
148
149 Here \verb|9 0 obj ... endobj| is the object capsule. The first number
150 is the object number (no.~9). The sequence \verb|5 0 R| is an object
151 reference, that is, a pointer to another object (no.~5). The second
152 number (here a zero) is currently not used in \PDFTEX; it is the version
153 number of the object. It is, for instance, used by \PDF\ editors, when
154 they replace objects by new ones.
155
156 When a viewer opens a \PDF\ file, it goes to the end of the file,
157 looking for the keyword \type{startxref}. The number after
158 \type{startxref} gives the absolute position (byte offset from the file
159 start) of the so\hyph called ``object cross-reference table'' that
160 begins with the keyword \type{xref}. This table in turn tells the byte
161 offsets of all objects that make up the \PDF\ file, providing fast
162 random access to the individual objects (here the \type{xref} table
163 shows 11~objects, numbered from~0 to~10; object no.~0 is always unused).
164 The actual starting point of the file's object structure is defined
165 after the \type{trailer}: the \type{/Root} entry points to the
166 \type{/Catalog} object (no.~9). In this object the viewer can find the
167 pointer \type{/Pages} to the page list object (no.~5). In our example we
168 have only one page. The trailer also usually holds an \type{/Info}
169 entry, which points to an object (no.~10) with a bit more about the
170 document. We can follow the thread:
171
172 \begin{quote}
173 \type{/Root} $\longrightarrow$ object~9 $\longrightarrow$
174 \type{/Pages} $\longrightarrow$ object~5 $\longrightarrow$
175 \type{/Kids} $\longrightarrow$ object~2 $\longrightarrow$
176 \type{/Contents} $\longrightarrow$ object~3
177 \end{quote}
178
179 As soon as we add annotations, a fancy word for hyperlinks and the like,
180 some more entries will be present in the catalog. We invite users to
181 take a look at the \PDF\ code of this file to get an impression of that.
182
183 The page content is a stream of drawing operations. Such a stream can be
184 compressed, where the level of compression can be set with
185 \cs{pdfcompresslevel} (compression is switched off for the title page).
186 Let's take a closer look at this stream in object~3. Often (but not in
187 our example) there is a transformation matrix, six numbers followed by
188 \type{cm}. As in \POSTSCRIPT, the operator comes after the operands.
189 Between \type{BT} and \type{ET} comes the text. A font is selected by a
190 \type{Tf} operator, which is given a font resource name \type{/F..} and
191 the font size. The actual text goes into parentheses \type{()} so that
192 it creates a \POSTSCRIPT\ string. The numbers in bracket pairs provide
193 horizontal movements like spaces and fine glyph positioning (kerning).
194 When one analyzes a file produced by a less sophisticated typesetting
195 engine, whole sequences of words can be recognized. In \PDF\ files
196 generated by \PDFTEX\ however, many words come out rather fragmented,
197 mainly because a lot of kerning takes place; in our example the
198 \type{80} moves the text \type{(elcome)} left towards the letter
199 \type{(W)} by 80/1000 of the font size. \PDF\ viewers in search mode
200 simply ignore the kerning information in these text streams. When a
201 document is searched, the search engine reconstructs the text from these
202 (string) snippets.
203
204 Every \type{/Page} object points also to a \type{/Resources} object
205 (no.~1) that gives all ingredients needed to assemble the page. In our
206 example only a \type{/Font} object (no.~4) is referenced, which in turn
207 tells that the text is typeset in \type{/Font} \type{/Times-Roman}. The
208 \type{/Font} object points also to a \type{/Widths} array (object no.~7)
209 that tells for each character by how much the viewer must move forward
210 horizontally after typesetting a glyph.
211
212 More details about the font can be found in the \type{/FontDescriptor}
213 object (no.~8); if a font file is embedded, this object points to the
214 font program stream. But as the Times-Roman font used for our example is
215 one of the 14 so\hyph called standard fonts that should always be present in
216 any \PDF\ viewer and therefore need not be embedded in the \PDF\ file,
217 it is left out here for brevity. However, when we use for instance a
218 Computer Modern Roman font, we have to make sure that this font is later
219 available to the \PDF\ viewer, and the best way to do this is to embed
220 the font. It's highly recommended nowadays to embed even the standard
221 fonts; you can't know how it looks exactly at the viewer side unless you
222 embed every font.
223
224 In this simple file we don't specify in what way the file should be
225 opened, for instance full screen or clipped. A closer look at the page
226 object no.~2 (\type{/Type/Page}) shows that a mediabox
227 (\type{/MediaBox}) is part of the page description. A mediabox acts like
228 the (high-resolution) bounding box in a \POSTSCRIPT\ file. \PDFTEX\
229 users can add dictionary entries to page objects with the
230 \cs{pdfpageattr} primitive.
231
232 Although in most cases macro packages will shield users from these
233 internals, \PDFTEX\ provides access to many of the entries described
234 here, either automatically by translating the \TEX\ data structures into
235 \PDF\ ones, or manually by pushing entries to the catalog, page, info or
236 self-created objects. One can for instance create an object by using
237 \cs{pdfobj}, after which \cs{pdflastobj} returns its number. So
238
239 \begin{verbatim}
240 \pdfobj { << /Type/ExtGState /LW 2 >> }
241 \end{verbatim}
242
243 \noindent inserts an object into the \PDF\ file (it creates a ``graphics
244 state'' object setting the line width to 2~units), and \cs{pdflastobj}
245 now returns the number \PDFTEX\ assigned to this object. Unless objects
246 are referenced by others, they will just end up as isolated entities,
247 not doing any real harm but bloating the \PDF\ file.
248
249 In general this rather direct way of pushing objects in the \PDF\ files
250 by primitives like \cs{pdfobj} is not very useful, and only makes
251 sense when implementing, say, fill\hyph in field support or annotation
252 content reuse. We will come to that later.
253
254 Of course, this is just the barest introduction to \PDF\ format. For
255 those who want to learn more about technical \PDF\ details, the best bet
256 is to read the \PDFReference\ (\useurl{pdfreference}).
257
258 We turn now to the specifics of \PDFTEX.
259
260 \chapter{Invoking \PDFTEX}
261
262 \PDFTEX\ has many command line options and can use many environment
263 variables and configuration file settings. Except for the simple and
264 rarely-used \type{-draftmode} and \type{-output-format} options, they
265 are all inherited from the common framework for \TeX\ engines as
266 implemented in \WEBC\ and Kpathsea. Their documentation is available at
267 \useurl{webc} and \useurl{kpathsea}.
268
269 Two additional environment variables need more description here: first,
270 \type{SOURCE_DATE_EPOCH} (introduced in version 1.40.17, 2016). If this
271 is set, it must be a positive integer (with one trivial exception: if it
272 is set but empty, that is equivalent to 0). Non-integer values cause a
273 fatal error. The value is used as the current time in seconds since the
274 usual Unix ``epoch'': the beginning of 1970-01-01, UTC. Thus, a value of
275 \type{32} would result in a \type{/CreationDate} and \type{/ModDate}
276 values of \type{19700101000032Z}. This is useful for reproducible builds
277 of documents. (See also \cs{pdfinfoomitdate}, \cs{pdfsuppressptexinfo},
278 et al.)
279
280 The second, related, environment variable is \type{FORCE_SOURCE_DATE}.
281 If this is set to~\type{1}, \TEX's time-related primitives are also
282 initialized from the value of \type{SOURCE_DATE_EPOCH}. These primitives
283 are \cs{year}, \cs{month}, \cs{day}, and \cs{time}. If
284 \type{SOURCE_DATE_EPOCH} is not set, setting \type{FORCE_SOURCE_DATE}
285 has no effect. If \type{FORCE_SOURCE_DATE} is unset, set to the empty
286 string, or set to~\type{0}, the primitives reflect the current time as
287 usual. Any other value elicits a warning, and the current time is used.
288 This is useful if one wants to make reproducible \PDF{}s for a set
289 of documents without changing them in any way, \eg\ an operating system
290 distribution with manuals that use \cs{today}. Except in such unusual
291 circumstances, it is better not to set this, and let the \TEX\
292 primitives retain the meaning they have always had.
293
294 In addition, if both \type{SOURCE_DATE_EPOCH} and
295 \type{FORCE_SOURCE_DATE} are set, \cs{pdffilemoddate} returns a value
296 in UTC, ending in \type{Z}. (The values of the environment variables are
297 irrelevant in this case.)
298
299 Finally, just to have the list of options and basic invocation at hand,
300 here is a verbatim listing of the \type{--help} and \type{--version}
301 output. All options can be specified with one or two dashes and
302 unambiguously abbreviated.
303
304 \myverbatiminput{incl/pdftex-help.txt}
305
306 \section{Macro packages supporting \PDFTEX}
307
308 Currently all mainstream macro packages offer \PDFTEX\ support, with
309 automatic detection of \PDFTEX\ as the engine being used. So normally
310 there is no need to explicitly turn on \PDFTEX\ support.
311
312 \begin{itemize}
313 \item For \LATEX\ users, the \type {hyperref} package (originally
314 written by Sebastian Rahtz and Heiko Oberdiek; now maintained by
315 the \LaTeX\ team), has substantial support for \PDFTEX\ and
316 provides access to most of its features. In the simplest and most
317 common case, the user merely needs to load \type{hyperref}, and
318 all cross\hyph references will be converted to \PDF\ hypertext
319 links. \PDF\ output is automatically selected, compression is
320 turned on, and the \PDF\ page size is set up correctly. Bookmarks
321 are created to match the table of contents.
322
323 \item The standard \LATEX\ packages \type{graphics}, \type{graphicx}, and
324 \type{color} also have built-in \PDFTEX\ support, which allows
325 use of color, text rotation, and graphics inclusion commands.
326
327 \item The \CONTEXT\ MkII system by Hans Hagen has full support
328 for \PDFTEX\ in its generalized hypertext features.
329 The latest \CONTEXT\ supports advanced \PDF\ output, but
330 uses a engine (\LMTX).
331
332 \item \PDF\ from \GNU\ \TEXINFO\ documents can be created by running
333 \PDFTEX\ on the \TEXINFO\ file, instead of \TEX. Alternatively,
334 run the shell command \type{texi2pdf} instead of \type{texi2dvi}.
335
336 \item For plain \TEX\ users, the \filename{miniltx.tex} file from the
337 \type{graphics-pln} package allows loading \type{graphics},
338 \type{graphicx}, and \type{color}. \EPLAIN\ provides additional
339 support for hyperlinks.
340
341 \item A modification of \filename {webmac.tex}, named \filename
342 {pdfwebmac.tex}, allows production of hyperlinked \PDF\ versions
343 of the literate source code written in \WEB, such as \PDFTEX.
344
345 \end{itemize}
346
347 For \TeX\ developers: as \PDFTEX\ generates the final \PDF\ output
348 without help of a postprocessor, macro packages that take care of these
349 \PDF\ features have to be set up properly. Tasks include handling color,
350 graphics, hyperlink support, threading, fonts, page imposition and
351 manipulation. All of these \PDF\hyph specific tasks can be controlled by
352 \PDFTEX's own primitives (a few also by a \PDFTEX\hyph specific
353 \verb|\special{pdf: ...}|). Any other \cs{special} commands, like the
354 ones defined for various \DVI\ postprocessors, are simply ignored by
355 \PDFTEX\ when in \PDF\ output mode; a warning is given for non\hyph
356 empty \cs{special} commands.
357
358 When a macro package written for classical \TEX\ with \DVI\ output is to
359 be modified for use with \PDFTEX, it is helpful to get some insight to
360 what extent \PDFTEX\hyph specific support is needed. This info can be
361 gathered, for instance, by outputting the various \cs{special} commands
362 via \cs{message}. as in:
363
364 \begin{verbatim}
365 \pdfoutput=1 \let\special\message
366 \end{verbatim}
367
368 or, if this leads to confusion,
369
370 \begin{verbatim}
371 \pdfoutput=1 \def\special#1{\write16{special: #1}}
372 \end{verbatim}
373
374 and see what happens. As soon as one \type{special:} message turns up,
375 one knows for sure that some kind of \PDFTEX\hyph specific support is
376 needed, and often the message itself gives a indication of what is
377 needed.
378
379 \chapter{Setting up fonts}
380
381 \PDFTEX\ can work with Type~1 and TrueType fonts (and to a small extent
382 also with OpenType fonts). Font files should be available and embedded
383 for all fonts used in the generated \PDF. It is possible to use
384 \METAFONT\hyph generated fonts in \PDFTEX---but it is strongly
385 recommended not to use these fonts if an equivalent is available in
386 Type~1 or TrueType format, if only because bitmap Type~3 fonts render
387 poorly under enlargement.
388
389 \section{Map files}
390 \label{sec.mapfile}
391
392 Font map files provide the connection between \TEX\ \TFM\ font files
393 and outline font file names. They contain also information about
394 re\hyph encoding arrays, partial font embedding (``subsetting''), and
395 character transformation parameters (like SlantFont and ExtendFont). Those
396 map files were first created for \DVI\ postprocessors. But, as \PDFTEX\
397 in \PDF\ output mode includes all \PDF\ processing steps, it also needs
398 to know about font mapping, and therefore reads in one or more map files.
399 Map files are not read in when \PDFTEX\ is in \DVI\ mode. Bitmap fonts
400 can (and normally should) be used without being listed in the map file.
401
402 By default, \PDFTEX\ reads the map file \filename{pdftex.map}. In \WEBC,
403 map files are searched for using the \type{TEXFONTMAPS} config file value
404 and environment variable. By default, the current directory and various
405 system directories are searched.
406
407 Within the map file, each font is listed on a single line. The syntax of
408 each line is upward\hyph compatible with \type{dvips} map files and can contain
409 the following fields (some are optional; explanations follow):
410
411 \begin{quote}
412 \varname{tfmname psname fontflags special encodingfile fontfile}
413 \end{quote}
414
415 Here are two (real-world) examples. All the values are explained in
416 detail in the following.
417
418 {\small \begin{verbatim}
419 cmr10 CMR10 <cmr10.pfb
420 ptmr8y NimbusRomNo9L-Regu " TeXnANSIEncoding ReEncodeFont " <texnansi.enc <utmr8a.pfb
421 \end{verbatim}
422 \par % needed for tagging; alternative: \begin{small}...\end{small}
423 % another alternative: \AddToHookNext{env/verbatim/begin}{\small}
424 }
425
426 It is mandatory that \varname{tfmname} is the first field. If a
427 \varname{psname} is given, it must be the second field. Similarly if
428 \varname{fontflags} is given it must be the third field (if
429 \varname{psname} is present) or the second field (if \varname{psname} is
430 left out). The positions of \varname{special}, \varname{encodingfile},
431 and \varname{fontfile} can be mixed.
432
433 \subsection{Map lines: \varname{tfmname}}
434 \label{sec.map-tfmname}
435
436 The \varname{tfmname} field specifies the name of the \TFM\ file for a
437 font---the file name given in a \TEX\ \cs{font} command. This name must
438 always be given, with no extension. Examples: \type{cmr10},
439 \type{ptmr8y}.
440
441 \subsection{Map lines: \varname{psname}}
442
443 The \varname{psname} field specifies the \POSTSCRIPT\ (or other outline)
444 font name, as defined within the outline font file. Examples:
445 \type{CMR10}, \type{NimbusRomNo9L-Regu}. It is highly recommended to use
446 the \varname{psname} field, but strictly speaking it is optional. It has
447 two main uses.
448
449 First, when a \PDF\ file is embedded by \cs{pdfximage}, the
450 \type{/BaseFont} names in the font dictionaries of Type~1 and Type~1C
451 (CFF) fonts from the embedded \PDF\ file are checked against this {\em
452 psname} field. If names match, the glyphs of that font will not be
453 copied from the embedded \PDF\ file, but instead a local font is opened,
454 and all needed glyphs will be taken from the Type~1 font file that is
455 mentioned in the map line (see \varname{fontfile} below). By this
456 collecting mechanism Type~1 glyphs can be shared between several
457 embedded \PDF\ files and with text that is typeset by \PDFTEX, which
458 helps keep the resulting \PDF\ file size smaller, if many files with
459 similar Type~1(C) fonts are embedded. Replacing Type~1 fonts from
460 embedded \PDF\ files requires that also a Type~1 font file name is in
461 the \varname{fontfile} field (see below).
462
463 Second, if a font file is not to be embedded into the \PDF\ output
464 (\varname{fontfile} field missing), then the \varname{psname} field will
465 be copied to the \type{/BaseFont} and \type{/FontName} dictionary
466 entries in the \PDF\ file, so that the \POSTSCRIPT\ font name will be
467 known to viewers and other \PDF-reading applications.
468
469 \subsection{Map lines: \emph{fontflags}}
470
471 The \emph{fontflags} field optionally specifies various characteristics
472 of the font. The following description of these flags is taken, with
473 slight modification, from the \PDFReference\ (the section on font
474 descriptor flags). Viewers may adapt their rendering to these flags,
475 especially when they substitute for a non-embedded font.
476
477 The value of the flags key in a font descriptor is a 32-bit integer that
478 contains a collection of boolean attributes. These attributes are true
479 if the corresponding bit is set to~1. The following table specifies the
480 meanings of the bits, with bit~1 being the least significant. Reserved
481 bits must be set to zero.
482
483 \begin{smalltable}
484 \begin{tabular}{cl}
485 \bf bit position & \bf semantics \cr
486 1 & Fixed-width font \cr
487 2 & Serif font \cr
488 3 & Symbolic font \cr
489 4 & Script font \cr
490 5 & Reserved \cr
491 6 & Uses the Adobe Standard Roman character set \cr
492 7 & Italic \cr
493 8--16 & Reserved \cr
494 17 & All-capitals font \cr
495 18 & Small-capitals font \cr
496 19 & Force bold at small text sizes \cr
497 20--32 & Reserved \cr
498 \end{tabular}
499 \end{smalltable}
500
501 The first several bits specify the general type of font. All characters
502 in a \emph{fixed-width} font (a.k.a.\ monospaced, typewriter) have the
503 same width, while characters in a proportional font have different
504 widths. Characters in a \emph{serif font} have short strokes drawn at an
505 angle on the top and bottom of character stems, while sans serif fonts
506 do not have such strokes. A \emph{symbolic font} contains symbols rather
507 than letters and numbers. Characters in a \emph{script font} resemble
508 cursive handwriting. An \emph{all-capitals} font, which is typically
509 used for display purposes such as titles or headlines, contains no
510 lowercase letters. It differs from a \emph{small-capitals} font in that
511 characters in the latter, while also capital letters, have been sized
512 and their proportions adjusted so that they have the same size and
513 stroke weight as lowercase characters in the same typeface family.
514
515 Bit~6 in the flags field indicates that the font's character set
516 conforms to the Adobe Standard Roman Character Set, or a subset of that,
517 and that it uses the standard names for those characters.
518
519 Finally, bit~19 is used to determine whether or not bold characters are
520 drawn with extra pixels even at very small text sizes. Typically, when
521 characters are drawn at small sizes on very low resolution devices such
522 as display screens, features of bold characters may appear only one pixel
523 wide. Because this is the minimum feature width on a pixel\hyph based device,
524 ordinary non\hyph bold characters also appear with one\hyph pixel wide features,
525 and thus cannot be distinguished from bold characters. If bit~19 is set,
526 features of bold characters may be thickened at small text sizes.
527
528 If the \varname{fontflags} field is not given, and the font is embedded,
529 \PDFTEX\ treats it as the value~4 (decimal, that is, bit position 3 is
530 set), a symbolic font. For non-embedded fonts, the default value is
531 \type{0x22}, a non-symbolic serif font. If you do not know the correct
532 value, it is best not to specify it at all, as specifying a bad value of
533 font flags may cause trouble in viewers. On the other hand this option
534 is not absolutely useless because it provides backward compatibility
535 with older map files (see the \varname{fontfile} description below).
536
537 \subsection{Map lines: \varname{special}}
538
539 The \varname{special} field specifies font manipulations in the same way
540 as \type{dvips}. Currently only the keywords \type{SlantFont} and
541 \type{ExtendFont} are interpreted; other instructions (notably
542 \type{ReEncodeFont} and its parameters, see \varname{encoding} below)
543 are ignored. The permitted \type{SlantFont} range is $-1..1$; for
544 \type{ExtendFont} it's $-2..2$. The text of the \varname{special} field
545 must be enclosed by ASCII double quote characters: \type{"}.
546
547 \subsection{Map lines: \varname{encodingfile}}
548
549 The \varname{encodingfile} field specifies the name of the file
550 containing the external encoding vector to be used for the font. The
551 encoding file name must have the extension \type{.enc}, and the file
552 name including extension must be given with either a preceding~\type{<}
553 character or a preceding~\type{<[}. The format of the encoding vector is
554 identical to that used by \type{dvips}. If no encoding is specified, the
555 font's built\hyph in default encoding is used. The
556 \varname{encodingfile} field may be omitted if you are sure that the
557 font resource has the correct built-in encoding. In general this option
558 is highly recommended, and it is required when subsetting a TrueType
559 font.
560
561 Starting with \PDFTEX\ version 1.40.19, an encoding file can also be
562 specified for bitmap \PK\ fonts. In this case, it assigns the glyph
563 names from the given encoding vector, which can be used with the
564 \cs{pdfglyphtounicode} primitive (q.v.). For example:
565
566 \begin{verbatim}
567 \pdfglyphtounicode{ffi}{0066 0066 0069} % normally: \input glyphtounicode
568 \pdfgentounicode=1
569 \pdfmapline{cmb10 <7t.enc}
570 \font\cmb=cmb10 \cmb ffi
571 \end{verbatim}
572
573 The result is a \PDF\ file with a correctly-labeled \type{/ffi}
574 character instead of the numeric character position in \type{cmb10.tfm}
575 (decimal 14).
576
577 \subsection{Map lines: \varname{fontfile}}
578
579 The \varname{fontfile} field sets the name of the font file to be
580 embedded into the \PDF\ output for a given \TeX\ font; the
581 \varname{tfmname}~$\leftrightarrow$~\varname{fontfile} mapping is the
582 most prominent use of the \filename{pdftex.map} file.
583
584 The font file name must refer to a Type~1 or TrueType font file. If the
585 \varname{fontfile} field is missing, no font embedding can take place; a
586 warning will be given, unless the \varname{psname} field contain one of
587 the 14 standard font names. Not embedding all fonts in a \PDF\ file is
588 troublesome, as this forces the \PDF\ viewer to use or synthesize a
589 replacement, typically with awful results.
590
591 The font file name should be preceded by one or two special characters,
592 specifying how to handle the font file:
593
594 \begin{itemize}
595 \item If the font file name is preceded by a \type{<} character
596 (as in \type{<cmr10.pfb}), the font file will be only partially
597 embedded in the \PDF\ output (``subsetted''), meaning that only
598 used glyphs are written to the \PDF\ file. This is the most
599 common use and is \emph{strongly recommended} for any font, as it
600 ensures the portability and reduces the size of the \PDF\ output.
601 Subsetted fonts are included in such a way that name and cache
602 clashes are minimized.
603
604 \item If the font file name is preceded by a double \type{<<}, the font
605 file will be included entirely---all glyphs of the font are
606 embedded, including even those not used in the document. Apart
607 from increasing the \PDF\ output size, this option may cause
608 troubles with TrueType fonts, so it is normally not recommended
609 for Type~1 or TrueType fonts. But this is currently the only mode
610 that allows the use of OpenType fonts. This mode might also be
611 useful in case the font is atypical and cannot be subsetted well
612 by \PDFTEX. {\em Beware: proprietary font vendors typically
613 forbid full font inclusion.}
614
615 \item As of \PDFTEX\ version 1.40.0, if no special character precedes
616 the font file name, it is ignored, with a warning. You achieve
617 exactly the same \PDF\ result if you just remove the font file
618 name from the map entry. Then the glyph widths that go into the
619 \PDF~file are extracted from the \TFM~file, and a font descriptor
620 object is created that contains approximations of the font
621 metrics for the selected font.
622
623 \item Specifying the {\em psname} and no font file name is only useful
624 as a last-ditch fallback when you do not want to embed the font
625 (\eg\ due to font license restrictions), but wish to use the font
626 metrics and let the \PDF\ viewer generate instances that look
627 close to the used font, in case the font resource is not
628 installed on the system where the \PDF\ output will be viewed or
629 printed. To use this feature, the font flags {\em must} be
630 specified, and it must have the bit~6 set on, which means that
631 only fonts with the Adobe Standard Roman character set can be
632 simulated. The only exception is the case of a symbolic font.
633 In these days of Unicode, these font approximations are not
634 likely to be useful.
635 \end{itemize}
636
637 If you encounter problematic lookups, for instance if \PDFTEX\ tries
638 to open a \type{.pfa} file instead of a \type{.pfb}, you can add
639 the suffix to the filename. In this respect, \PDFTEX\ completely relies
640 on the Kpathsea library.
641
642 For Type~1 and TrueType fonts, the font file will be included only once
643 in the \PDF\ output, regardless of how many \TeX\ \cs{font} instances
644 are used in the document. For instance, given
645
646 \begin{verbatim}
647 \font\a = cmr12
648 \font\b = cmr12 at 11pt
649 \end{verbatim}
650
651 the outline file \type{cmr12.pfb} will only be included once in the
652 \PDF, and merely scaled down to create the instance for \cs{b}.
653
654 If a used font is not present in the map files, \PDFTEX\ will try to use
655 \PK~fonts as most \DVI\ drivers do, creating \PK~fonts on-the-fly if
656 needed. This is the normal, and recommended, way to use bitmap fonts.
657
658 \subsection{Map lines: summary}
659
660 To summarize this rather complex story, let's look at some more example
661 map lines. The most common way is to embed only a subset of glyphs from
662 a font for a particular desired encoding, here~\type{8r}:
663
664 \begin{verbatim}
665 ptmri8r Times-Italic <8r.enc <ptmri8a.pfb
666 \end{verbatim}
667
668 Without re-encoding it looks like this:
669
670 \begin{verbatim}
671 cmr10 CMR10 <cmr10.pfb
672 \end{verbatim}
673
674 \type{SlantFont} and \type{ExtendFont} fields are specified as with
675 \type{dvips}:
676
677 \begin{verbatim}
678 psyro StandardSymL ".167 SlantFont" <usyr.pfb
679 pcrr8rn Courier ".85 ExtendFont" <8r.enc <pcrr8a.pfb
680 \end{verbatim}
681
682 Entirely embed a font into the \PDF\ file without and with re-encoding
683 (not typically useful):
684
685 \begin{verbatim}
686 fmvr8x MarVoSym <<marvosym.pfb
687 pgsr8r GillSans <8r.enc <<pgsr8a.pfb
688 \end{verbatim}
689
690 A TrueType font can be used in the same way as a Type~1 font:
691
692 \begin{verbatim}
693 verdana8r Verdana <8r.enc <verdana.ttf
694 \end{verbatim}
695
696 Finally, a few cases with non-embedded fonts. If the font file is
697 missing, the viewer application will have to use its own approximation
698 of the missing font (with and without re-encoding):
699
700 \begin{verbatim}
701 ptmr8r Times-Roman <8r.enc
702 psyr Symbol
703 \end{verbatim}
704
705 In the final example the numerical font flags (bit position 6) specify
706 using the Adobe Standard Roman character set, so the viewer might try an
707 approximation:
708
709 \begin{verbatim}
710 pgsr8r GillSans 32
711 \end{verbatim}
712
713 Not embedding fonts is rather risky and should generally be avoided. The
714 recommendation these days is to embed all fonts, even the 14 standard
715 ones.
716
717 \section{Helper tools for TrueType fonts: \texttt{ttf2afm}}
718
719 As mentioned above, \PDFTEX\ can work with TrueType fonts. Defining
720 TrueType fonts is similar to Type~1. The only extra thing to do with
721 TrueType is to create a \TFM\ file. There is a program called
722 \type{ttf2afm} in the \PDFTEX\ distribution which can be used to extract
723 \AFM\ from TrueType fonts (another conversion program is
724 \type{ttf2pt1}). Basic usage of \type{ttf2afm}:
725
726 \begin{verbatim}
727 ttf2afm -e encfile.enc -o output.afm input.ttf
728 \end{verbatim}
729
730 A TrueType file can be recognized by its suffix \filename{ttf}.
731 If no \type{-o} option is given, \type{ttf2afm} writes the output \AFM\
732 to standard output.
733
734 The optional \varname{encfile} specifies the encoding, which is the same
735 as the encoding vector used in map files for \PDFTEX\ and \type{dvips}.
736 That is, it must be an 8-bit encoding, not Unicode. If the encoding is
737 not given, all the glyphs of the \AFM\ output will be mapped to
738 \type{/.notdef}. If we need to know which glyphs are available in the
739 font, we can run \type{ttf2afm} without any \type{-e} to get all glyph
740 names. The resulting \AFM\ file can be used to generate a \TFM\ by
741 applying the \filename {afm2tfm} utility.
742
743 To use a new TrueType font the minimal steps may look like below, supposing
744 that a map file \filename {test.map} is used.
745
746 \begin{verbatim}
747 ttf2afm -e 8r.enc -o times.afm times.ttf
748 afm2tfm times.afm -T 8r.enc
749 echo "times TimesNewRomanPSMT <8r.enc <times.ttf" >>test.map
750 \end{verbatim}
751
752 TrueType fonts have some limitations in comparison with Type~1 fonts:
753
754 \begin{itemize}
755 \item To subset a TrueType font, the font must be specified as re\hyph
756 encoded, therefore an encoding vector must be given.
757 \item TrueType fonts used in embedded \PDF\ files are kept
758 untouched; they are not replaced or merged with the same font
759 used in the document, as happens with Type~1.
760 \item The special effects SlantFont\slash ExtendFont did not work
761 before version 1.40.0.
762 \end{itemize}
763
764 For much more about \PDFTEX\ and TrueType fonts, including many details
765 on handling glyph names, see ``A closer look at TrueType fonts and
766 \PDFTEX'', \titleref{TUGboat} 30:1 (2009), pp.~32\hyph 34,
767 \useurl{thanhtruetypetub}.
768
769 \chapter{\PDFTEX\ primitives}
770 \label{sec.primitives}
771
772 Here follows a description of the primitives added by \PDFTEX\ to the
773 original \TEX\ engine (other extensions by \ETEX, \MLTEX\ and \ENCTEX\
774 are not described). Many of these primitives are described further in
775 the \filename {samplepdf.tex} file in the \PDFTEX\ distribution (q.v.).
776
777 If the output is \DVI, then the \PDFTEX-specific dimension parameters
778 are not used at all. However, some \PDFTEX\ integer parameters can
779 affect \DVI\ as well as \PDF\ output (specifically, \cs{pdfoutput} and
780 \cs{pdfadjustspacing}).
781
782 A warning to macro writers: if you define macros whose names start with
783 \cs{pdf}, you risk name clashes with new primitives that may be
784 introduced in future versions of \PDFTEX.
785
786 General warning: many of these new primitives, for example \cs{pdfdest}
787 and \cs{pdfoutline}, write their arguments directly to the \PDF\ output
788 file (when producing \PDF), as \PDF\ string constants. This means that
789 \emph{you} (or, more likely, the macros you write) must escape
790 characters as necessary (namely \cs{}, \type{(}, and \type{)}.
791 Otherwise, an invalid \PDF\ file may result. The \type{hyperref} and
792 \TEXINFO\ packages have code which may serve as a starting point for
793 implementing this, although it will certainly need to be adapted to any
794 particular situation.
795
796 \section{Document setup}
797
798 \subsection{\cs{pdfoutput}}
799 \pdftexprimitive{\Syntax{\cs{pdfoutput} \Whatever{integer}}}
800
801 This parameter specifies whether the output format should be \DVI\ or
802 \PDF. A positive value means \PDF\ output, otherwise (default 0) one
803 gets \DVI\ output. This primitive is the only one that must be set to
804 produce \PDF\ output (the command-line option \type{-output-format=pdf}
805 may alternatively be used); all other primitives are optional. This
806 parameter cannot be specified \emph{after} shipping out the first page.
807 In other words, to get \PDF\ output, we have to set \cs{pdfoutput}
808 before \PDFTEX\ the first page.
809
810 A simple way of making macros aware of \PDFTEX\ in both \PDF\ or \DVI\
811 mode is:
812
813 \begin{verbatim}
814 \ifx\pdfoutput\undefined \csname newcount\endcsname\pdfoutput \fi
815 \ifcase\pdfoutput DVI CODE \else PDF CODE \fi
816 \end{verbatim}
817
818 Using the \type{ifpdf.sty} file, which works with both \LATEX\ and plain
819 \TeX, is a cleaner way of doing this. Originally, the simple test
820 \verb|\ifx\pdfoutput\undefined| sufficed; but for many years, the
821 \PDFTEX\ engine is used in distributions also for non-\PDF\ formats
822 (\eg\ \LATEX), so \cs{pdfoutput} may be defined even when the output
823 format is \DVI.
824
825 \subsection{\cs{pdfmajorversion}, \cs{pdfminorversion}}
826 \pdftexprimitive{\Syntax{\cs{pdfmajorversion} \Whatever{integer}}}
827 \pdftexprimitive{\Syntax{\cs{pdfminorversion} \Whatever{integer}}}
828
829 Together, these two primitives specify the \PDF\ version for generated \PDF\
830 output. The defaults compiled into the \PDFTEX\ program are
831 \cs{pdfmajorversion=1} and \cs{pdfminorversion=4}, thus \PDF~1.4
832 is generated by default.
833
834 However, distributions typically alter the engine's compiled default
835 minor version of~4 when building formats. For example, as of 2010,
836 \TEXLIVE\ sets \cs{pdfminorversion=5} when formats are built. This is
837 so object compression can be enabled (see \cs{pdfobjcompress} below).
838
839 This value also defines the highest \PDF\ version for included \PDF{}s
840 to be allowed without error, by default (see
841 \cs{pdfinclusionerrorlevel}).
842
843 The values for both must be $\ge1$ but are not checked further.
844 Furthermore, they are set independently; setting only
845 \cs{pdfmajorversion=2} would result in \PDF~2.4 output; it's
846 necessary to additionally set \cs{pdfminorversion}.
847
848 If specified, these primitives must appear before any data is written to
849 the generated \PDF\ file. The \cs{pdfmajorversion} primitive was
850 introduced in \PDFTEX\ 1.40.21. \cs{pdfminorversion} was originally a
851 synonym of the \cs{pdfoptionpdfminorversion} command, which is now
852 obsolete. \introduced{1.30.0}
853
854 \subsection{\cs{pdfcompresslevel}}
855 \pdftexprimitive{\Syntax{\cs{pdfcompresslevel} \Whatever{integer}}}
856
857 This integer parameter specifies the level of stream compression. Zero
858 means no compression, 1~means fastest, 9~means best, $2..8$ means
859 something in between. A value outside this range will be adjusted to the
860 nearest meaningful value. This parameter is read each time \PDFTEX\
861 starts a stream.
862
863 This compression applies to text, inline graphics, and embedded \PNG\
864 images (but only if they are un- and re-compressed during the embedding
865 process). It is implemented by the \type{zlib} library).
866
867 Setting \cs{pdfcompresslevel=0} is useful for \PDF\ stream debugging.
868
869 \subsection{\cs{pdfobjcompresslevel}}
870 \pdftexprimitive{\Syntax{\cs{pdfobjcompresslevel} \Whatever{integer}}}
871
872 This integer parameter controls the compression of non-stream objects.
873 If specified, the parameter must appear before any data is written to
874 the \PDF\ output. \introduced{1.40.0}
875
876 In the \PDF-1.4 specification, non-stream objects had to be written in
877 the \PDF\ file as clear text, uncompressed. The \PDF-1.5 specification
878 allows collecting non-stream objects as ``compressed objects'' into
879 ``object stream'' objects (\type{/Type/ObjStm}, see the \PDFReference,
880 5th~ed., \S3.4.6). At the end of the \PDF\ file, an \type{/XRef}
881 cross-reference stream is then written out instead of the object table.
882 This can result in a considerably smaller \PDF\ file, particularly if
883 lots of annotations and links are used.
884
885 The writing of compressed objects is enabled by setting
886 \cs{pdfobjcompresslevel} to a value between~1 and~3; it's disabled if~0
887 (default). Object compression also requires
888 $\cs{pdfminorversion}\ge5$ (or $\cs{pdfmajorversion}\ge2$), else
889 a warning is given and the compression is disabled. The value of
890 \cs{pdfobjcompresslevel} is clipped to the range $0..3$, but using
891 values outside this range is not recommended (for future extension).
892
893 Values for \cs{pdfobjcompresslevel} have the following effects:
894
895 \begin{itemize}
896 \item When set to~0, no object streams are generated at all.
897
898 \item When set to~1,
899 all non-stream objects are compressed with the exception of any objects
900 coming with embedded \PDF\ files (``paranoid'' mode, to avoid yet unknown
901 problems), and also the \type{/Info} dictionary is not compressed for
902 clear-text legibility.
903
904 \item When set to~2, also all non-stream objects coming
905 with embedded \PDF\ files are compressed, but the \type{/Info} dictionary
906 is still not compressed.
907
908 \item Finally, when set to~3, all non-stream objects
909 are compressed, including the \type{/Info} dictionary (this means that
910 the \type{/Info} can't be read as clear text any more). If object streams
911 are to be used, currently \cs{pdfobjcompresslevel=2} is recommended,
912 and is so specified in some distributions, including \TEXLIVE~2010 and later.
913 \end{itemize}
914
915 \emph{Compatibility caveats:} \PDF\ files generated with object
916 streams enabled can't be read with (sufficiently old) \PDF\ viewers that
917 don't understand \PDF-1.5 files. For widest distribution and unknown
918 audience, don't activate object stream writing. The \PDF-1.5 standard
919 describes also a hybrid object compression mode that gives some backward
920 compatibility, but this is currently not implemented, as \PDF-1.5 was
921 rather quickly adopted by modern \PDF\ viewers. Also not implemented is
922 the optional \type{/Extends} key.
923
924 \subsection{\cs{pdfdecimaldigits}}
925 \pdftexprimitive{\Syntax{\cs{pdfdecimaldigits} \Whatever{integer}}}
926
927 This integer parameter specifies the numeric accuracy of real
928 coordinates as written to the \PDF\ file. It gives the maximal number of
929 decimal digits after the decimal point. Valid values are in the range
930 $0..4$. A higher value means more precise output, but also results in a
931 larger file size and more time to display or print. In most cases the
932 optimal value is~2. This parameter does not influence the precision of
933 numbers used in raw \PDF\ code, like that used in \cs{pdfliteral} and
934 annotation action specifications; also multiplication items (\eg\
935 scaling factors) are not affected and are always output with best
936 precision. This parameter is read when \PDFTEX\ writes a real number to
937 the \PDF\ output.
938
939 When including huge \METAPOST\ images using \filename {supp-pdf.tex}, one can
940 limit the accuracy to two digits with \cs{twodigitMPoutput}.
941
942 \subsection{\cs{pdfhorigin}}
943 \pdftexprimitive{\Syntax{\cs{pdfhorigin} \Whatever{dimen}}}
944
945 This parameter can be used to set the horizontal offset of the output
946 box from the top left corner of the page. A value of 1~inch corresponds
947 to the normal \TEX\ offset. This parameter is read when \PDFTEX\ starts
948 shipping out a page to the \PDF\ output.
949
950 For all normal purposes, this parameter should always be kept at 1~true
951 inch. If you want to shift text on the page, use \TEX's own \cs{hoffset}
952 primitive. To avoid surprises, after global magnification has been
953 changed by the \cs{mag} primitive, the \cs{pdfhorigin} parameter should
954 still be 1~true inch, \eg\ by setting \cs{pdfhorigin=1 true in} after
955 the \cs{mag} setting. Or, you can preadjust the \cs{pdfhorigin} value
956 before typing \cs{mag}, so that its value after the \cs{mag} command
957 ends up at 1~true inch again.
958
959 \subsection{\cs{pdfvorigin}}
960 \pdftexprimitive{\Syntax{\cs{pdfvorigin} \Whatever{dimen}}}
961
962 This parameter is the vertical companion of \cs{pdfhorigin}, and the
963 notes above regarding \cs{mag} and true dimensions apply. Also keep
964 in mind that the \TEX\ coordinate system starts in the top left corner
965 (downward), while \PDF\ coordinates start at the bottom left corner
966 (upward).
967
968 \subsection{\cs{pdfpagewidth}}
969 \pdftexprimitive{\Syntax{\cs{pdfpagewidth} \Whatever{dimen}}}
970
971 This dimension parameter specifies the page width of the \PDF\ output
972 (the screen, the paper, etc.). \PDFTEX\ reads this parameter when it
973 starts shipping out a page. If magnification has been changed by the
974 \cs{mag} primitive, check that this parameter reflects the desired true
975 page width. When part of the page falls off the paper or screen, it's
976 quite possible that this parameter is set wrong.
977
978 If the value is set to zero, the page width is calculated as
979
980 \[
981 \hbox{\textit{width}}_{\hbox{\scriptsize box being shipped out}}
982 + 2 \times (\cs{horigin} + \hbox{\cs{hoffset}}).
983 \]
984 It is not wise to rely on this default calculation, since box widths may
985 vary unexpectedly.
986
987 \subsection{\cs{pdfpageheight}}
988 \pdftexprimitive{\Syntax{\cs{pdfpageheight} \Whatever{dimen}}}
989
990 Similar to the previous item, this dimension parameter specifies the
991 page height of the \PDF\ output; the notes above apply. If set to zero,
992 the page height will be calculated analogously to the above.
993
994 \section{Document info and catalog}
995 \label{sec.docinfocatalog}
996
997 \subsection{\cs{pdfomitinfodict}}
998 \pdftexprimitive{\Syntax{\cs{pdfomitinfodict} \Whatever{integer}}}
999
1000 If nonzero, omit the \type{/Info} dictionary completely, as required by
1001 the \PDF\ A-4 standard. \introduced{1.40.25}
1002
1003 \subsection{\cs{pdfinfo}}
1004 \pdftexprimitive{\Syntax{\cs{pdfinfo} \Something{general text}}}
1005
1006 This primitive allows the user to specify information for the document
1007 info dictionary. Provided information can be extracted from the output
1008 \PDF\ by, for instance, the \type{pdfinfo} program.
1009
1010 The \Something{general text} is a collection of key\hyph value\hyph
1011 pairs. The key names are preceded by a \type{/}, and the values, being
1012 strings, are given between parentheses. All keys, and the primitive
1013 itself, are optional. Possible
1014 keys are:\newline
1015 \type{/Title},\newline
1016 \type{/Author},\newline
1017 \type{/Subject},\newline
1018 \type{/Keywords},\newline
1019 \type{/Producer} (defaults to \hbox{\tt pdfTeX-\currentpdftex}),\newline
1020 \type{/Creator} (defaults to \type{TeX}),\newline
1021 \type{/CreationDate} (defaults to current date and time, with time zone),\newline
1022 \type{/ModDate} (same default as \type{/CreationDate}),\newline
1023 \type{/Trapped} (defaults to \type{/False},\newline
1024 \type{/PTEX.Fullbanner} (defaults to the \cs{pdftexbanner} string, q.v.).
1025
1026 \type{/CreationDate} and \type{/ModDate} are expressed in the form
1027 \type{D:YYYYMMDDhhmmssTZ}, where `\type{D:}' is a constant string
1028 prefix, \type{YYYY} is the year, \type{MM} is the month, \type{DD} is
1029 the day, \type{hh} is the hour, \type{mm} is the minutes, \type{ss} is
1030 the seconds, and \type{TZ} is an optional string denoting the time zone,
1031 \type{Z} for universal time. For example, this is the Unix epoch, the
1032 beginning of 1970-01-01 UTC, in this format: \type{D:19700101000000Z}.
1033 If the time zone is not UTC, it is given as \type{+HH'mm'} or
1034 \type{-HH'mm'}, indicating an offset of the given hours and minutes from
1035 UTC, with the given either later (\type{+}) or earlier (\type{-}) than
1036 UTC. For more details, see the \PDFReference, \S7.9.4.
1037
1038 Multiple appearances of \cs{pdfinfo} are concatenated. Usually if a key
1039 is given more than once, the first appearance will be used, but this is
1040 viewer\hyph dependent. Except for standard \TeX\ macro expansion,
1041 \PDFTEX\ does not perform any further operations in the
1042 \Something{general text} provided by the user.
1043
1044 Here is an example of using \cs{pdfinfo} to include the
1045 information not supplied by \PDFTEX:
1046
1047 \begin{verbatim}
1048 \pdfinfo {
1049 /Title (example.pdf)
1050 /Author (Tom and Jerry)
1051 /Subject (Example)
1052 /Keywords (mouse, cat)
1053 }
1054 \end{verbatim}
1055
1056 \subsection{\cs{pdfinfoomitdate}}
1057 \pdftexprimitive{\Syntax{\cs{pdfinfoomitdate} \Whatever{integer}}}
1058
1059 If nonzero, omit the \type{/CreationDate} and \type{/ModDate} keys from
1060 the document info dictionary described above. This can be useful in
1061 making reproducible \PDF{}s. \introduced{1.40.17}
1062
1063 \subsection{\cs{pdfsuppressptexinfo}}
1064 \pdftexprimitive{\Syntax{\cs{pdfsuppressptexinfo} \Whatever{integer}}}
1065
1066 This value is treated as a bit mask, specifying which \type{PTEX.*} keys
1067 to omit from the output:
1068
1069 \begin{smalltable}
1070 \begin{tabular}{cl}
1071 \bf value & \bf suppresses \cr
1072 1 & \type{PTEX.Fullbanner} \cr
1073 2 & \type{PTEX.FileName} \cr
1074 4 & \type{PTEX.PageNumber} \cr
1075 8 & \type{PTEX.InfoDict} \cr
1076 \end{tabular}
1077 \end{smalltable}
1078
1079 \noindent Thus, the value \type{-1}, setting all the bits, suppresses
1080 everything.
1081
1082 \type{PTEX.Fullbanner} is included by default in the general document
1083 info dictionary, as mentioned under \cs{pdfinfo} above. The other
1084 \type{PTEX.*} keys are included when a \PDF\ is included in the document
1085 (and not otherwise), as described in section~\ref{sec.addpdfkeys}.
1086
1087 This conditional suppression can be useful in making reproducible
1088 \PDF{}s. \introduced{1.40.17}
1089
1090 \subsection{\cs{pdfcatalog}}
1091 \pdftexprimitive{\Syntax{\cs{pdfcatalog} \Something{general text}
1092 \Optional{\Literal{openaction} \Something{action spec}}}}
1093
1094 Similar to the document info section is the document catalog, where
1095 possible keys are \type{/URI}, which specifies the base \URL\ of the
1096 document, and \type {/PageMode}, which determines how the \PDF\ viewer
1097 displays the document on startup. The possibilities for the latter are
1098 given in this table:
1099
1100 \begin{smalltable}
1101 \begin{tabular}{ll}
1102 \bf value & \bf meaning \cr
1103 \tt /UseNone & neither outline nor thumbnails visible \cr
1104 \tt /UseOutlines & outline visible \cr
1105 \tt /UseThumbs & thumbnails visible \cr
1106 \tt /FullScreen & full\hyph screen mode \cr
1107 \end{tabular}
1108 \end{smalltable}
1109
1110 The default \type{/PageMode} setting is \type{/UseNone}. In full\hyph
1111 screen mode, there is no menu bar, window controls, nor any other window
1112 present.
1113
1114 After the \Something{general text} of the catalog, a construct
1115 \Literal{openaction} \Something{action spec} can be given, where
1116 \Literal{openaction} is a \PDFTEX\ keyword, and \Something{action spec}
1117 specifies the action to be taken when opening the document. This
1118 \Something{action spec} is the same as for internal links; see
1119 section~\ref{sec.linking}.
1120
1121 Several settings can be made in one \cs{pdfcatalog} call, for
1122 example:
1123
1124 \begin{verbatim}
1125 \pdfcatalog {
1126 /PageMode /FullScreen
1127 } openaction goto page 2 {/Fit}
1128 \end{verbatim}
1129
1130 \subsection{\cs{pdfcreationdate}}
1131 \pdftexprimitive{\Syntax{\cs{pdfcreationdate} \Whatever{expandable}}}
1132
1133 Expands to the date string \PDFTEX\ uses in the info dictionary of the
1134 document, \eg\ for this file: {\tt\pdfcreationdate}. \introduced{1.30.0}
1135
1136 \subsection{\cs{pdfnames}}
1137 \pdftexprimitive{\Syntax{\cs{pdfnames} \Something{general text}}}
1138
1139 This primitive inserts the \Something{general text} to the \type{/Names}
1140 array. The text must conform to the specifications as laid down in the
1141 \PDFReference, or the document may be invalid.
1142
1143 \subsection{\cs{pdftrailer}}
1144 \pdftexprimitive{\Syntax{\cs{pdftrailer} \Something{general text}}}
1145
1146 This command puts its argument text verbatim into the file trailer
1147 dictionary. Example: \verb|\pdftrailer{/mytrlrkey /mytrlrval}|.
1148 \introduced{1.11a}
1149
1150 \subsection{\cs{pdftrailerid}}
1151 \pdftexprimitive{\Syntax{\cs{pdftrailerid} \Something{general text}}}
1152
1153 Use the \Something{general text} to seed the \type{/ID} value in the
1154 trailer, instead of the default combination of the input file
1155 name and starting time. If the argument is empty, the \type{/ID} is
1156 omitted entirely. Example: \verb|\pdftrailerid{}|. This can be useful
1157 in making reproducible \PDF{}s. \introduced{1.40.17}
1158
1159 \subsection{\cs{pdfuseptexunderscore}}
1160 \pdftexprimitive{\Syntax{\cs{pdfuseptexunderscore} \Whatever{integer}}}
1161
1162 If this parameter is zero, and \cs{pdfmajorversion} is $<2$, use
1163 `\type{/PTEX.} as the prefix for the relevant \type{/Info} keys, as was
1164 done through 2024. If this parameter is $>0$, or \cs{pdfmajorversion} is
1165 $\ge2$, use `\type{PTEX_}', with underscore instead of period. For
1166 example, if \cs{pdfmajorversion=2}, the key \type{/PTEX_Fullbanner} will
1167 be defined instead of \type{/PTEX.Fullbanner}.
1168
1169 Using \type{_} is required by updates to the PDF 32000-2-2020 standard,
1170 and/or by validators; for backwards compatibility, PDF 1.x output still
1171 uses \type{.}\ by default.
1172 \introduced{1.40.27}
1173
1174 \section{Fonts}
1175
1176 \subsection{\cs{pdfadjustspacing}}
1177 \pdftexprimitive{\Syntax{\cs{pdfadjustspacing} \Whatever{integer}}}
1178
1179 This primitive controls whether font expansion happens (this operation
1180 is described in detail at \cs{pdffontexpand}). By default,
1181 \cs{pdfadjustspacing} is set to~0; then font expansion is disabled, so
1182 that the \PDFTEX\ output is identical to that from the original \TEX\
1183 engine.
1184
1185 Font expansion can be activated in two modes. When \cs{pdfadjustspacing}
1186 is set to~1, font expansion is applied \emph{after} \TEX's normal
1187 paragraph breaking routines have broken the paragraph into lines. In
1188 this case, line breaks are identical to standard \TEX\ behavior.
1189
1190 When set to~2, the width changes that are the result of stretching and
1191 shrinking are taken into account \emph{while} the paragraph is broken
1192 into lines. In this case, line breaks are likely to be different from
1193 those of standard \TEX. Paragraphs may well become longer or shorter.
1194
1195 Both alternatives require a collection of \TFM\ files that are
1196 related to the \Something{stretch} and \Something{shrink} settings
1197 for the \cs{pdffontexpand} primitive, unless this is given with the
1198 \type{autoexpand} option.
1199
1200 \subsection{\cs{pdffontexpand}}
1201 \pdftexprimitive{\Syntax{\cs{pdffontexpand}
1202 \Something{font} \Something{stretch} \Something{shrink}
1203 \Something{step} \Optional{\Literal{autoexpand}}}}
1204
1205 This extension to \TEX's font definitions controls a major \PDFTEX\
1206 feature called \emph{font expansion}. To enable font expansion,
1207 \cs{pdfadjustspacing} must be set to a value greater than zero. We
1208 describe the basic process with an example:
1209
1210 \begin{verbatim}
1211 \font\somefont=sometfm at 10pt
1212 \pdffontexpand\somefont 30 20 10 autoexpand
1213 \pdfadjustspacing=2
1214 \end{verbatim}
1215
1216 The \verb|30 20 10| means this: ``hey \TEX, when line breaking is going
1217 badly, you may stretch the glyphs from this font as much as 3\% or
1218 shrink them as much as 2\%.'' For practical reasons \PDFTEX\ uses
1219 discrete expansion steps, in this example, 1\%.
1220
1221 Roughly speaking, the idea is as follows: When \TEX\ cannot break a line
1222 in the appropriate way, the unbreakable parts of the last word may stick
1223 into the margin. When \PDFTEX\ sees this, it will try to scale (shrink)
1224 the glyphs in that line using fixed steps, until the line fits. When
1225 lines are too spacey, the opposite happens: \PDFTEX\ starts scaling
1226 (stretching) the glyphs until the white space gaps are acceptable. This
1227 glyph stretching and shrinking is called \emph{font expansion}.
1228
1229 There are two different modes for font expansion, depending on whether
1230 \type{autoexpand} is specified:
1231
1232 \begin{enumerate}
1233 \item If the \type{autoexpand} keyword is given---this is
1234 recommended mode---only a single map entry is needed for all expanded
1235 font versions, using the name of the unexpanded \TFM\ file
1236 (\varname{tfmname} in section~\ref{sec.map-tfmname}). No expanded
1237 \varname{tfmname} versions need be mentioned (indeed, they are ignored),
1238 as \PDFTEX\ generates expanded instances of the unexpanded \TFM\ data
1239 structures and keeps them in its memory. As of \PDFTEX~1.40.0, the
1240 \type{autoexpand} work is done within the page stream by modification of
1241 the text matrix (\PDF\ operator ``\type{Tm}''), and not at the font file
1242 level, giving the advantage that it now works not only with Type~1 but
1243 also with TrueType and OpenType fonts (and even without embedding a font
1244 file; but that's not recommended). In this mode \PDFTEX\ requires only
1245 unexpanded font files.
1246
1247 \item Second, if the \type{autoexpand} keyword is not given, setting up
1248 font expansion requires considerably more work, as there must be map
1249 entries for \TFM\ files in all required expansion values. The expanded
1250 \varname{tfmname} variants are constructed by adding the font expansion
1251 value to the \varname{tfmname} of the base font, \eg\ there must be a
1252 map entry with \varname{tfmname} \type{sometfm+10} for 1\% stretch or
1253 \type{sometfm-15} for 1.5\% shrink. This also means that for each
1254 expanded font variant a \TFM\ file with properly expanded metrics must
1255 exist. In addition to the \TFM\ file, it is necessary to provide, for
1256 each expansion value, an individually crafted font file with the
1257 expanded glyphs. Thus, this allows the absolute best possible output,
1258 controlling the glyphs for every expanded variant of the font. It is a
1259 rare document indeed for this to be worth the trouble.
1260
1261 One technical drawback of non-\type{autoexpand} mode is that all needed
1262 individual font files need to be embedded in the \PDF\ output for each
1263 expanded font, leading to significantly larger \PDF\ files than in
1264 \type{autoexpand} mode.
1265
1266 Another caveat for non-\type{autoexpand} mode: when \cs{pdffontexpand}
1267 is executed, \PDFTEX\ immediately loads two fonts, at the maximum
1268 stretch and shrink; in our example, \type{sometfm+30} and
1269 \type{sometfm-20}. (If they aren't available, \type{mktextfm} may be
1270 uselessly called, and then an error message issued.) This happens even
1271 if those fonts never end up being used, which is arguably undesirable,
1272 but hard to change. It is not a problem when using \type{autoexpand}.
1273 \end{enumerate}
1274
1275 The font expansion mechanism is inspired by an optimization first
1276 introduced by Prof.~Hermann Zapf, which in itself goes back to
1277 optimizations used in the early days of typesetting: use different
1278 glyphs to optimize the grayness of a page. So, there are many, slightly
1279 different~a's, e's, etc. For practical reasons \PDFTEX\ does not use
1280 such huge glyph collections; it uses horizontal scaling instead. This is
1281 sub\hyph optimal, and possibly offensive to the design, though the
1282 expansions are tiny. It is up to the user to decide whether such
1283 slightly remastered fonts are acceptable. As an example, this
1284 document is typeset with font expansion and margin kerning activated
1285 (via the \texttt{microtype} \LaTeX\ package).
1286
1287 \subsection{\cs{efcode}}
1288 \pdftexprimitive{\Syntax{\cs{efcode} \Something{font}
1289 \Something{8-bit number} \Whatever{integer}}}
1290
1291 We haven't yet told the whole story. One can imagine that some glyphs
1292 are visually more sensitive to stretching or shrinking than others. Then
1293 the \cs{efcode} primitive can be used to influence the expandability of
1294 individual glyphs within a given font, as a factor applied to the
1295 expansion setting from the \cs{pdffontexpand} primitive. The syntax is
1296 similar to \cs{sfcode} (but with the \Something{font} required), and it
1297 defaults to~1000, meaning 100\% expandability. The given integer value
1298 is clipped to the range $0..1000$, corresponding to a usable
1299 expandability range of $0..100$\%. Examples:
1300
1301 \begin{verbatim}
1302 \efcode\somefont`A=800
1303 \efcode\somefont`O=0
1304 \end{verbatim}
1305
1306 Here the A in \cs{somefont} may only stretch or shrink by up to 80\% of
1307 the current expansion value for that font, and expansion for the~O is
1308 disabled. The actual expansion is still bound to the steps as defined by
1309 \cs{pdffontexpand} primitive.
1310
1311 Changes to this table are global, \ie\ ignore \TeX's usual grouping,
1312 and apply only to the given \Something{font}.
1313
1314 \subsection{\cs{pdfprotrudechars}}
1315 \pdftexprimitive{\Syntax{\cs{pdfprotrudechars} \Whatever{integer}}}
1316
1317 Yet another way of optimizing paragraph breaking is to let certain
1318 characters move into the margin (`character protrusion'). Character
1319 protrusion is disabled when \cs{pdfprotrudechars=0} or negative.
1320
1321 When \cs{pdfprotrudechars=1}, the glyphs qualified as such will make
1322 this move when applicable, without changing the line-breaking. When
1323 \cs{pdfprotrudechars=2} (or greater), character protrusion will be taken
1324 into account while considering breakpoints, so line-breaking might be
1325 changed. This qualification and the amount of shift are set by the
1326 primitives \cs{rpcode} and \cs{lpcode}.
1327
1328 If you want to protrude an item other than a character (\eg\ an
1329 \cs{hbox}), you can do so by padding the item with an invisible
1330 zero\hyph width character for which protrusion is activated.
1331
1332 \subsection{\cs{rpcode}, \cs{lpcode}}
1333 \pdftexprimitive{\Syntax{\cs{rpcode} \Something{font}
1334 \Something{8-bit number} \Whatever{integer}}}
1335 \pdftexprimitive{\Syntax{\cs{lpcode} \Something{font}
1336 \Something{8-bit number} \Whatever{integer}}}
1337
1338 The amount that a character from a given font may shift into the right
1339 margin (`character protrusion') is set by the primitive \cs{rpcode}. The
1340 protrusion distance is the integer value given to \cs{rpcode},
1341 multiplied by 0.001em from the current font. The given integer value is
1342 clipped to the range $-1000..1000$, corresponding to a usable protrusion
1343 range of $-$1em..1em. \cs{lpcode} is exactly analogous to \cs{rpcode},
1344 but affects the amount by which characters may protrude into the left
1345 margin.
1346
1347 Examples:
1348
1349 \begin{verbatim}
1350 \rpcode\somefont`,=200
1351 \rpcode\somefont`-=150
1352 \end{verbatim}
1353
1354 Here the comma may shift by 0.2em into the margin and the hyphen by
1355 0.15em. All these small bits and pieces will help \PDFTEX\ to give
1356 you better paragraphs (use \cs{rpcode} judiciously; don't overdo it).
1357
1358 Remark: old versions of \PDFTEX\ use the character width as measure. This
1359 was changed to a proportion of the em-width after \THANH\ finished his
1360 master's thesis.
1361
1362 Changes to these tables are global, \ie\ ignore \TeX's usual grouping,
1363 and apply only to the given \Something{font}.
1364
1365 \subsection{\cs{leftmarginkern}, \cs{rightmarginkern}}
1366 \pdftexprimitive{\Syntax{\cs{leftmarginkern} \Something{box number}
1367 \Whatever{expandable}}}
1368 \pdftexprimitive{\Syntax{\cs{rightmarginkern} \Something{box number}
1369 \Whatever{expandable}}}
1370
1371 The \cs{leftmarginkern} \Something{box number} primitive expands to the
1372 width of the margin kern at the left side of the horizontal list stored
1373 in \cs{box} \Something{box number}. The expansion string includes the
1374 unit \type{pt}. \Eg\ when the left margin kern of \cs{box0} amounts to
1375 $-$10pt, \cs{leftmarginkern0} will expand to \type{-10pt}. The primitive
1376 \cs{rightmarginkern} works analogously for the right margin.
1377 \introducedplural{1.30.0}
1378
1379 These are auxiliary primitives to make character protrusion more
1380 versatile. When using the \TEX\ primitives \cs{unhbox} or \cs{unhcopy},
1381 the margin kerns at either end of the unpackaged hbox will be removed
1382 (\eg\ to avoid weird effects if several hboxes are unpackaged behind
1383 each other into the same horizontal list). These \cs{unhbox} or
1384 \cs{unhcopy} commands are often used together with \cs{vsplit} for dis-
1385 and re\hyph assembling of paragraphs, \eg\ to add line numbers.
1386 Paragraphs treated like this do not show character protrusion by
1387 default, as the margin kerns have been removed during the unpacking
1388 process.
1389
1390 The \cs{leftmarginkern} and \cs{rightmarginkern} primitives allow
1391 access to the margin kerns and store them away before unpackaging the
1392 hbox. \Eg\ the following code snippet restores margin kerning of
1393 a horizontal list stored in \cs{box}\cs{testline}, resulting in a hbox with
1394 the original margin kerning, now inserted by ordinary kerns.
1395
1396 \begin{verbatim}
1397 \dimen0=\leftmarginkern\testline
1398 \dimen1=\rightmarginkern\testline
1399 \hbox to\hsize{\kern\dimen0\unhcopy\testline\kern\dimen1}
1400 \end{verbatim}
1401
1402 \subsection{\cs{letterspacefont}}
1403 \pdftexprimitive{\Syntax{\cs{letterspacefont} \Something{control sequence}
1404 \Something{font} \Something{integer}}}
1405
1406 This primitive creates an instance of \Something{font} with the widths
1407 of all glyphs increased by \Something{integer} thousandths of an em (as
1408 defined by \Something{font}). The effect is letter spacing, but the
1409 glyphs are actually wider, as the sidebearings are increased, so a
1410 single glyph will take more space. For instance, the following creates a
1411 font \cs{lsfont} whose glyphs are all 1.2pt larger than those of
1412 \cs{normalfont}:
1413
1414 \begin{verbatim}
1415 \font\normalfont=myfont at 12pt
1416 \letterspacefont\lsfont\normalfont 100
1417 \end{verbatim}
1418
1419 Negative values are allowed for \Something{integer}.
1420 Letter spacing works natively in \PDF\ mode only, unless special fonts are
1421 devised (in our example, a \type{myfont+100ls} font), as with font expansion.
1422
1423 \subsection{\cs{pdfcopyfont}}
1424 \pdftexprimitive{\Syntax{\cs{pdfcopyfont} \Something{control sequence}
1425 \Something{font}}}
1426
1427 This primitive defines \Something{control sequence} as a synonym for
1428 \Something{font}.
1429
1430 \subsection{\cs{pdffakespace}}
1431 \pdftexprimitive{\Syntax{\cs{pdffakespace}}}
1432
1433 Always insert a fake interword space in the output (PDF only; this
1434 primitive is an error in DVI mode), regardless of the values of
1435 \cs{pdfinterwordspaceon} and \cs{pdfinterwordspaceoff} (q.v.). Example:
1436
1437 \begin{verbatim}
1438 Text with a fake interword \pdffakespace space.
1439 \end{verbatim}
1440 \introduced{1.40.15}
1441
1442 \subsection{\cs{pdffontattr}}
1443 \pdftexprimitive{\Syntax{\cs{pdffontattr} \Something{font}
1444 \Something{general text}}}
1445
1446 This primitive inserts the \Something{general text} into the
1447 \type{/Font} dictionary. The text must conform to the specifications as
1448 laid down in the \PDFReference, or the document may be invalid. For
1449 examples, see the \type{cmap} and \type{CJK} packages.
1450
1451 \subsection{\cs{pdffontname}}
1452 \pdftexprimitive{\Syntax{\cs{pdffontname} \Something{font}
1453 \Whatever{expandable}}}
1454
1455 In \PDF\ files produced by \PDFTEX\ one can recognize a font resource
1456 by the prefix~\type{/F} followed by a number, for instance \type{/F12}
1457 or \type{/F54}. For a given \TEX\ \Something{font}, this primitive
1458 expands to the number from the corresponding font resource name.
1459 \Eg\ if \type{/F12} corresponds to some \TEX\ font \cs{foo}, then
1460 \cs{pdffontname}\cs{foo} expands to the number~\type{12}.
1461
1462 In the current implementation, when \cs{pdfuniqueresname} (see below)
1463 is set to a positive value, the \cs{pdffontname} still returns only the
1464 number from the font resource name, without the appended random string.
1465
1466 \subsection{\cs{pdffontobjnum}}
1467 \pdftexprimitive{\Syntax{\cs{pdffontobjnum} \Something{font}
1468 \Whatever{expandable}}}
1469
1470 This command is similar to \cs{pdffontname}, but it returns the \PDF\
1471 object number of the font dictionary instead of the number from the font
1472 resource name. \Eg\ if the font dictionary (\type{/Type/Font}) in \PDF\
1473 object~3 corresponds to some \TEX\ font \cs{foo}, then
1474 \cs{pdffontobjnum}\cs{foo} gives the number~\type{3}.
1475
1476 Use of \cs{pdffontname} and \cs{pdffontobjnum} allows users full
1477 access to all the font resources used in a document.
1478
1479 \subsection{\cs{pdffontsize}}
1480 \pdftexprimitive{\Syntax{\cs{pdffontsize} \Something{font}
1481 \Whatever{expandable}}}
1482
1483 This primitive expands to the font size of the given font, with unit
1484 \type{pt}. \Eg\ when using the plain \TeX\ macro package, the call
1485 \cs{pdffontsize}\cs{tenrm} expands to \type{10.0pt}.
1486
1487 \subsection{\cs{pdfgentounicode}}
1488 \pdftexprimitive{\Syntax{\cs{pdfgentounicode} \Whatever{integer}}}
1489
1490 By default, \PDFTEX\ does not include a \type{/ToUnicode} resource when
1491 including fonts in the output. Such a resource (also called a CMap
1492 resource) maps glyph names to Unicode characters in a \PDF\ file.
1493 Lacking such a resource, it is the \PDF\ reader which determines how and
1494 whether searching in the \PDF\ file works. In practice, searching for
1495 basic \ASCII\ characters generally works, but searching for anything
1496 beyond those, including ligatures such as `fi', is likely to fail.
1497
1498 If \cs{pdfgentounicode} is set to \type{1} when the job ends, the
1499 \type{/ToUnicode} resource will be included in the output, with mappings
1500 for Type~1 fonts used---unless \cs{pdfnobuiltintounicode} (q.v.) is set
1501 for a given font.
1502
1503 The mapping is created as follows: for each glyph in the font, look for
1504 its \type{ToUnicode} value in a global hash table. By default that
1505 global hash table is empty, in which case \PDFTEX\ merely emits a
1506 warning. Entries are added to the table using the command
1507 \cs{pdfglyphtounicode}, described next.
1508
1509 \subsection{\cs{pdfglyphtounicode}}
1510 \pdftexprimitive{\Syntax{\cs{pdfglyphtounicode} \Something{general text}
1511 \Something{general text}}}
1512
1513 The first argument is the name of a glyph, the second is a string of Unicode
1514 numeric values denoting characters, separated by spaces. For instance:
1515
1516 \begin{verbatim}
1517 \pdfgentounicode=1
1518 \pdfglyphtounicode{ff}{0066 0066}
1519 \end{verbatim}
1520
1521 \noindent maps the \type{ff} ligature to a pair of \type{f} characters
1522 (whose code is \type{U+0066}, that is, \ASCII\ \type{0x66}).
1523
1524 Once a single \cs{pdfglyphtounicode} definition is made, whether it is
1525 used or not, another feature comes into play: all glyph names of the
1526 form \type{uniXXXX} or \type{uXXXX} are mapped to the natural
1527 \type{U+XXXX}. Many fonts use this style of naming.
1528
1529 In addition, the \type{glyphtounicode.tex} file (distributed with
1530 \PDFTEX\ and other software) contains thousands of such definitions,
1531 covering most common glyph names. So, for practical purposes, one would
1532 probably want:
1533
1534 \begin{verbatim}
1535 \input glyphtounicode
1536 \pdfgentounicode=1
1537 \end{verbatim}
1538
1539 \noindent (\LATEX\ users could load the \type{cmap} package to achieve
1540 the same effect.)
1541
1542 By default, these glyph name-to-unicode mappings are global. Thus,
1543
1544 \begin{verbatim}
1545 \pdfglyphtounicode{abc}{1234}
1546 \end{verbatim}
1547
1548 \noindent would map the glyph named \type{abc} to \type{U+1234} for
1549 every font. However, it's possible to make a mapping for a single font
1550 using a \type{tfm:} prefix:
1551
1552 \begin{verbatim}
1553 \pdfglyphtounicode{tfm:foo/abc}{5678}
1554 \end{verbatim}
1555
1556 \noindent means that for the font \type{foo.tfm}, only, the glyph
1557 \type{abc} is mapped to \type{U+5678}.
1558
1559 Glyph names sometimes contain a dot, as in \type{somechar.sc}. \PDFTEX\
1560 simply strips the dot and everything after it before looking up the
1561 name, so in this case it would look for \type{somechar} (even if
1562 \type{somechar.sc} exists in the mappings, it will not be used). This
1563 behavior could be made smarter if there is a demand for it.
1564
1565 \subsection{\cs{pdfincludechars}}
1566 \pdftexprimitive{\Syntax{\cs{pdfincludechars} \Something{font}
1567 \Something{general text} \Whatever{expandable}}}
1568
1569 This command causes \PDFTEX\ to treat the characters in \Something{general
1570 text} as if they were used with \Something{font}, which means that the
1571 corresponding glyphs will be embedded into the font resources in the \PDF\
1572 output. Nothing is appended to the list being built.
1573
1574 \subsection{\cs{pdfinterwordspaceon}, \cs{pdfinterwordspaceoff},
1575 \cs{pdfspacefont}}
1576 \pdftexprimitive{\Syntax{\cs{pdfinterwordspaceon}}}
1577 \pdftexprimitive{\Syntax{\cs{pdfinterwordspaceoff}}}
1578 \pdftexprimitive{\Syntax{\cs{pdfspacefont} \Something{general text}}}
1579
1580 The first two commands insert corresponding whatsit items which turn
1581 on/off generation of faked interword spaces in the \PDF\ output (they
1582 cause errors in \DVI\ output). This allows for better reflowing of text
1583 on the fly by \PDF\ readers, better extraction of textual content, and
1584 is required by \PDF/A. It does not affect the normal \TeX\ justification
1585 with glue of the typeset output.
1586
1587 This works roughly as follows: with \cs{pdfinterwordspaceon},
1588 \PDFTEX\ will guess when an interword space should be inserted, based on
1589 movement within some limits in horizontal direction. When found,
1590 \PDFTEX\ inserts a true space character into the \PDF\ page description
1591 for the viewers, and adjusts the next movement so that the next
1592 character will be in the expected position, according to normal \TEX\
1593 behavior.
1594
1595 Where does that ``true space character'' come from?
1596 There are two possibilities.
1597
1598 \begin{itemize}
1599 \item If the current font has a real space character, it is used.
1600 \PDFTEX\ considers a font to have such a space character if 1)~the font
1601 has an encoding vector (\type{.enc} file) specified in its map entry,
1602 and 2)~the encoding has a glyph named \type{space} (that is, the
1603 PostScript name \type{/space}) at slot 32. For example, the font
1604 \type{texnansi-lmr10} uses the encoding file \type{lm-texnansi.enc},
1605 which has such an entry.
1606
1607 \item
1608 If the current font does not have such a space character (this is the
1609 case for most traditional \TEX\ fonts, such as \type{cmr10} and
1610 \type{ec-lmr10}), \PDFTEX\ will use the space character from a special
1611 fallback font named (by default) \type{pdftexspace}[\type{.tfm}].
1612 \PDFTEX\ automatically defines a map entry for this font which looks
1613 like this:
1614
1615 \begin{verbatim}
1616 \pdfmapline{=pdftexspace PdfTeX-Space <pdftexspace.pfb}
1617 \end{verbatim}
1618
1619 The \type{pdftexspace.tfm} and \type{pdftexspace.pfb} files are expected
1620 to be available to \PDFTEX\ just like any other font. (They are
1621 distributed with \PDFTEX.) The \type{pdftexspace} font was constructed
1622 by hand; it has a space character that is .333em (and no other
1623 characters).
1624
1625 A different fallback font for the space character can be given via
1626 \verb|\pdfspacefont{myfont}|. This is most likely to be useful for
1627 testing and debugging. In this case, \PDFTEX\ assumes that the given font
1628 has a real space character at slot 32, and that any necessary
1629 corresponding map entry exists. For example:
1630
1631 \begin{verbatim}
1632 \pdfspacefont{texnansi-lmr10} % use space char from this font if
1633 % current font has no space char
1634 \end{verbatim}
1635 \end{itemize}
1636
1637 History: Before \PDFTEX\ version 1.40.25, no check was made for a
1638 \type{space} character in the current font, the fallback font was named
1639 \type{dummy-space}, and its space character was tiny, 0.001em. It turned
1640 out that \PDF\ viewers were unhappy with this tiny space, especially
1641 with tagged \PDF.
1642
1643 Example of usage (see also the \type{fake-interword-space.tex} test file):
1644
1645 \begin{verbatim}
1646 Text with no interword spaces.
1647
1648 \pdfglyphtounicode{space}{0020}
1649 \pdfinterwordspaceon
1650
1651 Switch to text with faked interword spaces.
1652
1653 \pdfinterwordspaceoff
1654
1655 Back to text with no interword spaces.
1656 \end{verbatim}
1657 \introducedplural{1.40.15, 1.40.25}
1658
1659 \subsection{\cs{pdfmapfile}}
1660 \pdftexprimitive{\Syntax{\cs{pdfmapfile} \Something{map filename}}}
1661
1662 This primitive is used for reading a font map file consisting of one or
1663 more font map lines. The name of the map file is given in the
1664 \Something{map filename} together with an optional leading modifier
1665 character, as explained below. If your map file isn't in the current
1666 directory or a standard system directory, you will need to set the
1667 \type{TEXFONTMAPS} variable (in \WEBC) or give an explicit path so that
1668 it will be found.
1669
1670 If no \cs{pdfmapfile} primitive is given, the default map file
1671 \filename{pdftex.map} will be read by \PDFTEX. Normally there is no need
1672 for a \PDFTEX\ user to bother about the \cs{pdfmapfile} or
1673 \cs{pdfmapline} primitives, as the main \TEX\ distributions provide
1674 helper tools to automatically assemble the default \type{pdftex.map}.
1675 (In \TEXLIVE, these tools are \type{updmap} and \type{updmap-sys}.)
1676
1677 There is a companion primitive \cs{pdfmapline} that allows scanning
1678 single map lines; its map line argument has the same syntax as the map
1679 lines from a map file. Both primitives can be used concurrently. The
1680 \cs{pdfmapfile} primitive is fast for reading external bulk font map
1681 information (many map lines collected in a map file), whereas the
1682 \cs{pdfmapline} allows putting the font map information for individual
1683 \TeX\ fonts directly in the \TeX\ source or a style file. With both
1684 primitives, the map line information is scanned by \PDFTEX\ identically.
1685 In the most common case, the data are put into a fresh internal map
1686 entry data structure, which is then consulted when a font is used.
1687
1688 When a \cs{pdfmapfile} or \cs{pdfmapline} primitive is executed by
1689 \PDFTEX, the argument (map file or map line) will be processed
1690 immediately, and the internal map entry database updated. The operation
1691 mode of the \cs{pdfmapfile} and \cs{pdfmapline} primitives is selected
1692 by an optional modifier character, one of \type{+}, \type{=}, \type{-},
1693 in front of the \varname{tfmname} field. This modifier defines how the
1694 individual map lines are going to be handled, and how a collision
1695 between an already registered map entry and a newer one is resolved:
1696 either by ignoring a later entry, or replacing or deleting an existing
1697 entry. In any case, map entries of fonts already in use are kept
1698 untouched. Here are two examples:
1699
1700 \begin{verbatim}
1701 \pdfmapfile{+myfont.map}
1702 \pdfmapline{+ptmri8r Times-Italic <8r.enc <ptmri8a.pfb}
1703 \end{verbatim}
1704
1705 When no modifier character is given (\eg\ \verb|\pdfmapfile{foo.map}|
1706 or\newline \verb|\pdfmapline{helv Helvetica}|) and there has been no
1707 previous call to one of these primitives, then the default map file
1708 \filename{pdftex.map} will \emph{not} be read. Apart from this case, the
1709 given map file will be processed as with the \type{+} modifier:
1710 duplicate later map entries within the file are ignored and a warning is
1711 issued. Thus, you can block reading of the default map file also with an
1712 empty \verb|\pdfmapfile{}| or \verb|\pdfmapline{}| early in the \TeX\
1713 file. Since the default map file is typically large, if you don't need
1714 it, these command variants might considerably speed up \PDFTEX\ startup.
1715
1716 If a modifier is given, before reading the items given as arguments to
1717 the present \cs{pdfmapfile} or \cs{pdfmapline}, the default map file
1718 will be read first---if this hasn't already been done or been prevented
1719 by the above blocking cases. The meaning of the modifiers:
1720
1721 \begin{itemize}
1722 \item \verb|\pdfmapfile{+foo.map}| reads the file \filename{foo.map};
1723 duplicate later map entries within the file are ignored and a warning is
1724 issued.
1725
1726 \item \verb|\pdfmapfile{=foo.map}| reads the file \filename{foo.map};
1727 matching map entries in the database are replaced by new entries from
1728 \filename{foo.map}, if they haven't already been used.
1729
1730 \item \verb|\pdfmapfile{-foo.map}| reads the file \filename{foo.map};
1731 matching map entries are deleted from the database, if they haven't
1732 already been used.
1733 \end{itemize}
1734
1735 In short, if you want to add support for a new font through an
1736 additional font map file while keeping all the existing mappings, use
1737 \verb|\pdfmapfile{+myfont.map}| or \verb|\pdfmapfile{=myfont.map}|.
1738
1739 If you want to use a base map file name other than \type{pdftex.map}, or
1740 change its processing options through a \PDFTEX\ format, you can do this
1741 by appending the \cs{pdfmapfile} command to the \cs{everyjob} token list
1742 for the \type{-ini} run, as in:
1743
1744 \begin{verbatim}
1745 \everyjob=\expandafter{\the\everyjob\pdfmapfile{+myspecial.map}}
1746 \dump
1747 \end{verbatim}
1748
1749 This would always read the file \type{myspecial.map} after the default
1750 \type{pdftex.map} file.
1751
1752 \subsection{\cs{pdfmapline}}
1753 \pdftexprimitive{\Syntax{\cs{pdfmapline} \Something{map spec}}}
1754
1755 Similar to \cs{pdfmapfile}, but here you give a single map line (exactly
1756 like the ones in map files) as an argument. The optional modifiers
1757 (\type{+-=}) have the same effect as with \cs{pdfmapfile}; see also the
1758 description above. Example:
1759
1760 \begin{verbatim}
1761 \pdfmapline{+ptmri8r Times-Italic <8r.enc <ptmri8a.pfb}
1762 \end{verbatim}
1763
1764 This primitive, especially the \verb|\pdfmapline{=...}| form, is useful
1765 for temporary quick checks of a new font map entry during development,
1766 before finally putting it into a map file.
1767
1768 As explained above, \verb|\pdfmapline{}|, like \verb|\pdfmapfile{}|,
1769 blocks reading of the default map file, if it comes early enough in the
1770 \TeX\ input. \introduced{1.20a}
1771
1772 \subsection{\cs{pdfmovechars}}
1773 \pdftexprimitive{\Syntax{\cs{pdfmovechars} \Whatever{integer}}}
1774
1775 Since \PDFTEX\ version 1.30.0 the primitive \cs{pdfmovechars} is
1776 obsolete, and its use merely leads to a warning. (This primitive
1777 specified whether \PDFTEX\ should try to move characters in range 0..31
1778 to higher slots; its sole purpose was to remedy certain bugs of early
1779 \PDF\ viewers.)
1780
1781 \subsection{\cs{pdfnobuiltintounicode}}
1782 \pdftexprimitive{\Syntax{\cs{pdfnobuiltintounicode} \Something{font}}}
1783
1784 The purpose of this command is to prevent \PDFTEX\ from generating the
1785 \type{ToUnicode}/CMap resource for the given font when
1786 \cs{pdfgentounicode=1}, most likely because the CMap resource is already
1787 generated by some other method. For instance, the \LATEX\ \type{cmap}
1788 package uses \cs{pdffontattr} to generate CMap resources.
1789
1790 Minimal example:
1791 \begin{verbatim}
1792 \font\f=cmb10
1793 \pdfnobuiltintounicode\f
1794 \f No unicode mappings for this output.
1795 \end{verbatim}
1796 \introduced{1.40.11}
1797
1798 \subsection{\cs{pdfnoligatures}}
1799 \pdftexprimitive{\Syntax{\cs{pdfnoligatures} \Something{font}}}
1800
1801 This disables all ligatures in the loaded font \Something{font}.
1802 \introduced{1.30.0}
1803
1804 \subsection{\cs{pdfomitcharset}}
1805 \pdftexprimitive{\Syntax{\cs{pdfomitcharset} \Whatever{integer}}}
1806
1807 If this primitive parameter is zero (the default), the \type{/CharSet}
1808 entry is included as usual for fonts in the \PDF\ output; if it is set
1809 to 1, then \type{/CharSet} is omitted. Other values may have other
1810 meanings in the future, so do not rely on them.
1811
1812 Explanation: This parameter was created because the \PDFA-1 standard
1813 requires \type{/CharSet}, whereas \PDFA-2 and \PDFA-3 allow it to be
1814 omitted but have extraordinary requirements, which \PDFTEX\ does not
1815 currently meet, if it is included.\introduced{1.40.20}
1816
1817 \subsection{\cs{pdfpkmode}}
1818 \pdftexprimitive{\Syntax{\cs{pdfpkmode} \Whatever{tokens}}}
1819
1820 The \cs{pdfpkmode} is a token register that sets the \METAFONT\ mode for
1821 pixel font generation. The contents of this register is dumped into the
1822 format, so one can (optionally) preset it. \introduced{1.30.0}
1823
1824 \subsection{\cs{pdfpkresolution}}
1825 \pdftexprimitive{\Syntax{\cs{pdfpkresolution} \Whatever{integer}}}
1826
1827 This integer parameter specifies the default resolution of embedded \PK\
1828 fonts and is read when \PDFTEX\ embeds a \PK\ font during finishing the
1829 \PDF\ output. As bitmap fonts may be rendered poorly, and in any case
1830 cannot be arbitrarily magnified, it is best to use outline fonts if
1831 possible.
1832
1833 \subsection{\cs{pdfsuppresswarningdupmap}}
1834 \pdftexprimitive{\Syntax{\cs{pdfsuppresswarningdupmap} \Whatever{integer}}}
1835
1836 Ordinarily, \PDFTEX\ gives a warning when a duplicate map entry for a
1837 given font is read, whatever the mechanism. However, sometimes it is
1838 useful to include map information within the document, using
1839 \cs{pdfmapfile} or \cs{pdfmapline}, even for fonts that happen to be
1840 installed on the system. Then seeing the warnings on every run is just
1841 noise; it can be suppressed by setting this parameter to a positive
1842 number. \introduced{1.40.13}
1843
1844 \subsection{\cs{pdftracingfonts}}
1845 \pdftexprimitive{\Syntax{\cs{pdftracingfonts} \Whatever{integer}}}
1846
1847 This integer parameter specifies the level of verbosity for the
1848 information about expanded fonts given in the log, \eg\ when
1849 \cs{tracingoutput=1}. If \cs{pdftracingfonts=0}, which is the default,
1850 the log shows the actual nonzero signed expansion value for each
1851 expanded letter within brackets, as in:
1852
1853 \begin{verbatim}
1854 ...\xivtt (+20) t
1855 \end{verbatim}
1856
1857 If \cs{pdftracingfonts=1}, the name of the \TFM\ file is also listed,
1858 together with the font size:
1859
1860 \begin{verbatim}
1861 ...\xivtt ([email protected]) t
1862 \end{verbatim}
1863
1864 Setting \cs{pdftracingfonts} to a value other than~0 or~1 is not
1865 recommended, to allow for future extensions. \introduced{1.30.0}
1866
1867 \subsection{\cs{pdfuniqueresname}}
1868 \pdftexprimitive{\Syntax{\cs{pdfuniqueresname} \Whatever{integer}}}
1869
1870 When this primitive is assigned a positive number, \PDF\ resource names
1871 will be made reasonably unique by appending a random string consisting
1872 of six \ASCII\ characters.
1873
1874 \subsection{\cs{tagcode}}
1875 \pdftexprimitive{\Syntax{\cs{tagcode} \Something{font}
1876 \Something{8-bit number} \Whatever{integer}}}
1877
1878 This primitive accesses a character's \type{char_tag} info. It is meant
1879 to delete \type{lig_tag} (the character's ligature/kerning program),
1880 \type{list_tag} (which indicates that the character belongs to a chain of
1881 ascending sizes) and/or \type{ext_tag} (which indicates that the character
1882 is extensible), with the following options: assigning \type{-7} or less
1883 clears all tags, \type{-6} clears \type{ext_tag} and \type{list_tag},
1884 \type{-5} clears \type{ext_tag} and \type{lig_tag}, \type{-4} clears
1885 \type{ext_tag}, \type{-3} clears \type{list_tag} and \type{lig_tag},
1886 \type{-2} clears \type{list_tag}, \type{-1} clears \type{lig_tag},
1887 and \type{0} or larger does nothing. Changes are irreversible and global.
1888
1889 Conversely, when queried, the primitive returns \type{0} if the tag's
1890 value is \type{no_tag}, \type{1} if \type{lig_tag} is set, \type{2} if
1891 \type{list_tag} is set or \type{4} (not~3) if \type{ext_tag} is set.
1892
1893 \section{Spacing}
1894
1895 Controlling spacing before and after characters was introduced in
1896 version 1.30, mostly to handle punctuation rules in different
1897 languages. The \cs{...code} tables here, like those in the previous
1898 section, operate globally, \ie\ ignore \TeX's usual grouping, and apply
1899 only to the given \Something{font}, not other instances of the
1900 underlying font.
1901
1902 \subsection{\cs{pdfadjustinterwordglue}}
1903 \pdftexprimitive{\Syntax{\cs{pdfadjustinterwordglue} \Whatever{integer}}}
1904
1905 If positive, adjustment of interword glue is enabled and controlled by the
1906 following three primitives.
1907
1908 \subsection{\cs{knbscode}}
1909 \pdftexprimitive{\Syntax{\cs{knbscode} \Something{font}
1910 \Something{8-bit number} \Whatever{integer}}}
1911
1912 The amount of space, in thousandths of an em, added to the natural width
1913 of the glue following a character (the name stands for ``kern before
1914 space'', although technically it is looking at glue items, not kern
1915 items). This amounts is clipped to the range $-1000..1000$. For
1916 instance, in the following example, glue after periods in the current
1917 font will be increased by .2em.
1918
1919 \begin{verbatim}
1920 \pdfadjustinterwordglue=1
1921 \knsbcode\font`\.=200
1922 \end{verbatim}
1923
1924 \subsection{\cs{stbscode}}
1925 \pdftexprimitive{\Syntax{\cs{stbscode} \Something{font}
1926 \Something{8-bit number} \Whatever{integer}}}
1927
1928 This works like \cs{knbscode}, but applies to the stretch component of
1929 the following glue.
1930
1931 \subsection{\cs{shbscode}}
1932 \pdftexprimitive{\Syntax{\cs{shbscode} \Something{font}
1933 \Something{8-bit number} \Whatever{integer}}}
1934
1935 Like \cs{stbscode}, but for the shrink component.
1936
1937 \subsection{\cs{pdfprependkern}}
1938 \pdftexprimitive{\Syntax{\cs{pdfprependkern} \Whatever{integer}}}
1939
1940 If positive, automatic insertion of kerns before characters is enabled.
1941
1942 \subsection{\cs{knbccode}}
1943 \pdftexprimitive{\Syntax{\cs{knbccode} \Something{font}
1944 \Something{8-bit number} \Whatever{integer}}}
1945
1946 The width of the kern, in thousandths of an em, inserted before a
1947 character. It is clipped to the range $-1000..1000$. For instance, with
1948 the following code, a .15em-kern will be inserted before all question
1949 marks in the current font (possibly useful for \eg\ French punctuation):
1950
1951 \begin{verbatim}
1952 \pdfprependkern=1
1953 \knbccode\font`\?=150
1954 \end{verbatim}
1955
1956 \subsection{\cs{pdfappendkern}}
1957 \pdftexprimitive{\Syntax{\cs{pdfappendkern} \Whatever{integer}}}
1958
1959 Same as \cs{pdfprependkern}, but for kerns inserted after characters.
1960
1961 \subsection{\cs{knaccode}}
1962 \pdftexprimitive{\Syntax{\cs{knaccode} \Something{font}
1963 \Something{8-bit number} \Whatever{integer}}}
1964
1965 Same as \cs{knbccode}, except the kern is inserted after the
1966 character. Such a kern is required for instance after a left guillemet
1967 in French punctuation.
1968
1969 \section{Vertical adjustments}
1970
1971 \subsection{\cs{pdfignoreddimen}}
1972 \pdftexprimitive{\Syntax{\cs{pdfignoreddimen} \Whatever{dimen}}}
1973
1974 This specifies the dimension value which must be assigned to the
1975 following four primitives so they are ignored. Default is
1976 \type{-1000pt}, and it should be modified with care since it also
1977 influences when a previous paragraph's depth is ignored (for instance,
1978 the plain \TEX\ macro \cs{nointerlineskip} should be modified
1979 accordingly).
1980
1981 \subsection{\cs{pdffirstlineheight}, \cs{pdflastlinedepth}}
1982 \pdftexprimitive{\Syntax{\cs{pdffirstlineheight} \Whatever{dimen}}}
1983 \pdftexprimitive{\Syntax{\cs{pdflastlinedepth} \Whatever{dimen}}}
1984
1985 These parameters specify the height of the first, resp.\ depth of the
1986 last, line of a paragraph, regardless of its content. They are read when
1987 the paragraph builder is called, and ignored when set to
1988 \cs{pdfignoreddimen}. By default, they are set to \type{-1000pt}, so
1989 they are ignored as long as the value of \cs{pdfignoreddimen} is not
1990 changed.
1991
1992 \subsection{\cs{pdfeachlineheight}, \cs{pdfeachlinedepth}}
1993 \pdftexprimitive{\Syntax{\cs{pdfeachlineheight} \Whatever{dimen}}}
1994 \pdftexprimitive{\Syntax{\cs{pdfeachlinedepth} \Whatever{dimen}}}
1995
1996 \cs{pdfeachlineheight} is similar to \cs{pdffirstlineheight}, but for
1997 all lines of a paragraph, including the first one, unless
1998 \cs{pdffirstlineheight} is specified.
1999
2000 \cs{pdfeachlinedepth} is the same, but for the depth.
2001
2002 \section{\PDF\ objects}
2003
2004 \subsection{\cs{pdfobj}}
2005 \pdftexprimitive{\Syntax{\cs{pdfobj} \Something{object type spec}
2006 \Modelist{h, v, m}}}
2007
2008 This command creates a raw \PDF\ object that is written to the \PDF\
2009 file as \verb|1 0 obj| \ldots\ \type{endobj}.
2010
2011 When \Something{object type spec} is not given, \PDFTEX\ no longer
2012 creates a dictionary object with contents \Something{general text}, as
2013 it did in the past.
2014
2015 When \Something{object type spec} is given as \Something{attr
2016 spec} \Literal{stream}, the object will be created as a stream with
2017 contents \Something{general text} and additional attributes in
2018 \Something{attr spec}.
2019
2020 When \Something{object type spec} is given as \Something{attr spec}
2021 \Literal{file}, then the \Something{general text} will be treated as a file
2022 name and its contents will be copied into the stream contents.
2023
2024 When \Something{object type spec} is given as \type{reserveobjnum}, just
2025 a new object number is reserved. The number of the reserved object is
2026 accessible via \cs{pdflastobj}. The object can later be filled with
2027 contents by \cs{pdfobj} \Literal{useobjnum} \Something{number}
2028 \Lbrace\Something{balanced text}\Rbrace, but the reserved object number
2029 can be used by other objects before it is defined, providing a
2030 forward\hyph referencing mechanism.
2031
2032 The object is kept in memory and will be written to the \PDF\ output only
2033 when its number is referred to by \cs{pdfrefobj} or when \cs{pdfobj}
2034 is preceded by \cs{immediate}. Nothing is appended to the list being
2035 built. The number of the most recently created object is accessible via
2036 \cs{pdflastobj}.
2037
2038 \subsection{\cs{pdflastobj}}
2039 \pdftexprimitive{\Syntax{\cs{pdflastobj} \Whatever{read-only integer}}}
2040
2041 This command returns the object number of the last object created by \type
2042 {\pdfobj}.
2043
2044 \subsection{\cs{pdfrefobj}}
2045 \pdftexprimitive{\Syntax{\cs{pdfrefobj} \Something{object number}
2046 \Modelist{h, v, m}}}
2047
2048 This command appends a whatsit item to the list being built. When the
2049 whatsit is searched at shipout time, \PDFTEX\ will write the object
2050 \Something{object number} to the \PDF\ output if it has not been written
2051 yet.
2052
2053 \subsection{\cs{pdfretval}}
2054 \pdftexprimitive{\Syntax{\cs{pdfretval} \Whatever{read-only integer}}}
2055
2056 Set to $-1$ if \cs{pdfobj} ignores an invalid object number. Perhaps
2057 this will be used to store the error status of other primitives in the
2058 future.
2059
2060 \section{Page and pages objects}
2061
2062 \subsection{\cs{pdfpagesattr}}
2063 \pdftexprimitive{\Syntax{\cs{pdfpagesattr} \Whatever{tokens}}}
2064
2065 \PDFTEX\ expands this token list when it finishes the \PDF\ output and
2066 adds the resulting character stream to the root \type{Pages}
2067 object. When defined, these are applied to all pages in the
2068 document. Some examples of attributes are \type{/CropBox}, the rectangle
2069 specifying the region of the page being displayed and printed, and
2070 \type{/Rotate}, the number of degrees (in multiples of 90) the page
2071 should be rotated clockwise when it is displayed or printed.
2072
2073 % /MediaBox is not a good example, since it will never take effect.
2074 \begin{verbatim}
2075 \pdfpagesattr
2076 { /Rotate 90 % rotate all pages by 90 degrees
2077 /CropBox [0 0 612 792] } % the crop size of all pages (in bp)
2078 \end{verbatim}
2079
2080 \subsection{\cs{pdfpageattr}}
2081 \pdftexprimitive{\Syntax{\cs{pdfpageattr} \Whatever{tokens}}}
2082
2083 This is similar to \cs{pdfpagesattr}, but has priority over it.
2084 It can be used to override any attribute given by \cs{pdfpagesattr}
2085 for an individual page. The token list is expanded when \PDFTEX\ ships out
2086 a page. The contents are added to the attributes of the current page.
2087
2088 If the \cs{pdfpageattr} value contains the string \type{/MediaBox},
2089 then \PDFTEX\ omits outputting its own \type{/MediaBox} value (which is
2090 \verb|[0 0 |\Something{\it page\_width} \Something{\it
2091 page\_height}\type{]}). (This behavior was introduced in version
2092 1.40.18.)
2093
2094 \subsection{\cs{pdfomitprocset}}
2095 \pdftexprimitive{\Syntax{\cs{pdfomitprocset} \Whatever{integer}}}
2096
2097 If this parameter is zero (the default), the \type{/ProcSet} array is
2098 included if \cs{pdfmajorversion} is~1, and omitted if
2099 $\cs{pdfmajorversion}\ge2$. If this parameter is $>0$, \type{/ProcSet}
2100 is always omitted; if it is $<0$, \type{/ProcSet} is always
2101 included. For information about what \type{/ProcSet} is, see the
2102 \PDFReference\ or other documentation.
2103
2104 \cs{ProcSet} was considered obsolete as of \PDF~1.4, but conforming
2105 writers should continue to output it. It was formally deprecated in
2106 \PDF~2.0.\introduced{1.40.25}
2107
2108 \subsection{\cs{pdfpageref}}
2109 \pdftexprimitive{\Syntax{\cs{pdfpageref} \Something{page number}
2110 \Whatever{expandable}}}
2111
2112 This primitive expands to the number of the page object that contains
2113 the dictionary for page \Something{page number}. If the page
2114 \Something{page number} does not exist, a warning will be issued,
2115 a fresh unused \PDF\ object will be generated, and \cs{pdfpageref}
2116 will expand to that object number.
2117
2118 \Eg\ if the dictionary for page~5 of the \TEX\ document is contained in
2119 \PDF\ object no.~18, \cs{pdfpageref5} expands to the number 18.
2120
2121 \subsection{\cs{pdfpageresources}}
2122 \pdftexprimitive{\Syntax{\cs{pdfpageresources} \Whatever{tokens}}}
2123
2124 These tokens are added to the resource dictionary for all pages, before
2125 the font, XObject, and ProcSet resources. For example:
2126
2127 \begin{verbatim}
2128 \pdfpageresources{/MyPageResourceAttribute /MyValue}
2129 \end{verbatim}
2130
2131 \section{Form XObjects}
2132
2133 The next three primitives support a \PDF\ feature called ``object
2134 reuse'' in \PDFTEX. The idea is first to create a `form XObject'. The
2135 content of this object corresponds to the content of a \TEX\ box; it can
2136 contain pictures and references to other form XObjects as well. After
2137 creation, the form XObject can be used multiple times by simply
2138 referring to its object number. This feature can be useful for large
2139 documents with many similar elements, to reduce the duplication of
2140 identical objects.
2141
2142 These commands behave similarly to \cs{pdfobj}, \cs{pdfrefobj} and
2143 \cs{pdflastobj} (described in the previous section), but instead of
2144 taking raw \PDF\ code, they handle text typeset by \TEX.
2145
2146 \subsection{\cs{pdfxform}}
2147 \pdftexprimitive{\Syntax{\cs{pdfxform}
2148 \Optional{\Something{attr spec}}
2149 \Optional{\Something{resources spec}}
2150 \Something{box number}
2151 \Modelist{h, v, m}}}
2152
2153 \noindent\Syntax{\Something{attr spec} \Means
2154 \Literal{attr} \Something{general text}
2155 \newline
2156 \Something{resources spec} \Means
2157 \Literal{resources} \Something{general text}
2158 }
2159
2160 This command creates a form XObject corresponding to the contents of the
2161 box \Something{box number}. The box can contain other raw objects, form
2162 XObjects, or images as well. However, it cannot contain annotations
2163 because those are laid out on a separate layer, are positioned
2164 absolutely, and have dedicated housekeeping. \cs{pdfxform} makes box
2165 \Something{box number} void, as \cs{box} does.
2166
2167 When \Something{attr spec} is given, the text will be written as an
2168 additional attribute into the form XObject dictionary. A
2169 \Something{resources spec} is similar, but the text will be added to the
2170 resources dictionary of the form XObject. The text given by
2171 \Something{attr spec} or \Something{resources spec} is written before
2172 other entries of the form dictionary and\slash or the resources
2173 dictionary and takes priority over later ones.
2174
2175 \subsection{\cs{pdfrefxform}}
2176 \pdftexprimitive{\Syntax{\cs{pdfrefxform} \Something{object number}
2177 \Modelist{h, v, m}}}
2178
2179 The form XObject is kept in memory and will be written to the \PDF\
2180 output only when its object number is referred to by \cs{pdfrefxform}
2181 or when \cs{pdfxform} is preceded by \cs{immediate}. Nothing is
2182 appended to the list being built. The number of the most recently created
2183 form XObject is accessible via \cs{pdflastxform}.
2184
2185 When issued, \cs{pdfrefxform} appends a whatsit item to the list being
2186 built. When the whatsit item is searched at shipout time, \PDFTEX\ will
2187 write the form \Something{object number} to the \PDF\ output if it is
2188 not written yet.
2189
2190 \subsection{\cs{pdflastxform}}
2191 \pdftexprimitive{\Syntax{\cs{pdflastxform} \Whatever{read-only integer}}}
2192
2193 The object number of the most recently created form XObject is accessible
2194 via \cs{pdflastxform}.
2195
2196 As said, this feature can be used for reusing information. This mechanism
2197 also plays a role in typesetting fill\hyph in forms. Such widgets sometimes
2198 have visuals that show up on user request, but are hidden otherwise.
2199
2200 \subsection{\cs{pdfxformname}}
2201 \pdftexprimitive{\Syntax{\cs{pdfxformname} \Something{object number}
2202 \Whatever{expandable}}}
2203
2204 In \PDF\ files produced by \PDFTEX\ one can recognize a form XObject by
2205 the prefix~\type{/Fm} followed by a number, for instance \type{/Fm2}.
2206 For a given form XObject number, this primitive expands to the number in
2207 the corresponding form XObject name. \Eg\ if \type{/Fm2} corresponds to
2208 some form XObject with object number 7, the \cs{pdfxformname7}
2209 expands to the number~\type{2}. \introduced{1.30.0}
2210
2211 \section{Graphics inclusion}
2212
2213 \PDF\ provides a mechanism for embedding graphic and textual objects:
2214 form XObjects. In \PDFTEX\ this mechanism is accessed by means of
2215 \cs{pdfxform}, \cs{pdflastxform} and \cs{pdfrefxform} (described in the
2216 previous section). A special kind of XObject is bitmap graphics and
2217 for manipulating them similar commands are provided.
2218
2219 Chapter~\ref{chap.graphics} provides a few more details about graphics
2220 handling in \PDFTEX.
2221
2222 \subsection{\cs{pdfximage}}
2223 \pdftexprimitive{\Syntax{\cs{pdfximage}
2224 \Optional{\Something{image attrs}}
2225 \Something{general text}
2226 \Modelist{h, v, m}
2227 }}
2228
2229 \noindent \Syntax{
2230 \Something{image attrs} \Means
2231 \Optional{\Something{rule spec}}
2232 \Optional{\Something{attr spec}}
2233 \Optional{\Something{page spec}}
2234 \Optional{\Something{named spec}}
2235 \Next
2236 \Optional{\Something{pdf box spec}}
2237 \Optional{\Something{colorspace spec}}
2238 }
2239
2240 \noindent\Syntax{
2241 \Something{rule spec} \Means
2242 (\Literal{width} \Or \Literal{height} \Or \Literal{depth})
2243 \Something{dimen} \Optional{\Something{rule spec}}
2244 \newline
2245 \Something{attr spec} \Means
2246 \Literal{attr} \Something{general text}
2247 \newline
2248 \Something{page spec} \Means
2249 \Literal{page} \Something{number}
2250 \newline
2251 \Something{named spec} \Means
2252 \Literal{named} \Something{general text}
2253 \newline
2254 \Something{pdf box spec} \Means
2255 \Literal{mediabox}
2256 \Or \Literal{cropbox}
2257 \Or \Literal{bleedbox}
2258 \Or \Literal{trimbox}
2259 \Or \Literal{artbox}
2260 \newline
2261 \Something{colorspace spec} \Means
2262 \Literal{colorspace} \Something{number}
2263 }
2264
2265 This command creates an image object from the filename given in
2266 \Something{general text}, \ie\ enclosed in braces.
2267
2268 The image type is specified by the extension of the given file name:
2269 \type{.png} stands for \PNG\ image, \type{.jpg} (or \type{.jpeg}) for
2270 \JPEG, \type{.jbig2} (preferred, but \type{.jb2} works also) for
2271 \JBIGTWO, and \type{.pdf} for \PDF\ file. However, after \PDFTEX\ has
2272 opened the file, it checks the file type first by checking the magic
2273 number at the file start, which gets precedence over the file name
2274 extension. This gives a certain degree of fault tolerance, if the file
2275 name extension is incorrect.
2276
2277 The image is kept in memory when this command is executed. It is written
2278 to the \PDF\ output only 1)~if the \cs{pdfximage} command is
2279 preceded by \cs{immediate}, or 2)~when its number is referred to by
2280 \cs{pdfrefximage} (q.v.).
2281
2282 \subsubsection{\cs{pdfximage}: \Somethingbf{rule spec} for image size}
2283
2284 The dimensions of the image can be controlled via \Something{rule spec}.
2285 The default values are zero for depth and ``running'' for height and
2286 width. If all of them are given, the image will be scaled to fit the
2287 specified values. If some (but not all) are given, the rest will be set
2288 to a value corresponding to the remaining ones so as to make the image
2289 size to yield the same proportion of $width : (height+depth)$ as the
2290 original image size, where depth is treated as zero. If no
2291 \Something{rule spec} is given then the image will have its natural
2292 size.
2293
2294 An image inserted at its natural size often has a resolution of
2295 \type{\pdfimageresolution} (see below) given in dots per inch in the
2296 output file. However, if an image contains metadata specifying the image
2297 resolution, the image will be scaled accordingly---unless (as of
2298 \PDFTEX\ 1.40.27, released in 2025) the embedded image metadata is
2299 patently incorrect, such as 1dpi x 1dpi, in which case \PDFTEX\ ignores
2300 the metadata and issues a warning. Otherwise the bogus data would
2301 typically lead to an arithmetic overflow error from \TEX.
2302
2303 The dimensions of an image can be accessed by using the
2304 \cs{pdfrefximage} command in a box and checking the box's dimensions:
2305
2306 \begin{verbatim}
2307 \setbox0=\hbox{\pdfximage{somefile.png}\pdfrefximage\pdflastximage}
2308 % now \wd0 and \ht0 are the natural size of the image.
2309 \end{verbatim}
2310
2311 \subsubsection{\cs{pdfximage}: \Somethingbf{attr spec}
2312 to add arbitrary PDF attributes}
2313
2314 Similarly to \cs{pdfxform}, the optional text given by \Something{attr
2315 spec} will be written as additional attributes of the image before other
2316 keys of the image dictionary. When using this, be aware that slightly
2317 different types of \PDF\ objects are created while including \PNG,
2318 \JPEG, or \JBIG2\ bitmaps and \PDF\ images.
2319
2320 \subsubsection{\cs{pdfximage}: \texttt{page} \Somethingbf{number}
2321 for included page by number}
2322
2323 If using a \PDF\ or \JBIG2\ image, \texttt{page} \Something{number} allows
2324 specifying which page of the document is to be included; a
2325 \Something{page spec} is irrelevant for the other two image formats.
2326 \Something{page spec} is {\tt page \Something{number}} to specify a page
2327 by number.
2328
2329 \subsubsection{\cs{pdfximage}: \texttt{named} \Somethingbf{dest}
2330 for included page by name}
2331
2332 For \PDF\ images, you may also reference a so-called ``named
2333 destination'' in the \PDF\ file with {\tt named \{\Something{destination
2334 name}\}}. Such named destinations are created by \type{hyperref}, for
2335 example.
2336
2337 \subsubsection{\cs{pdfximage}: \Somethingbf{pdf box spec}
2338 for final bounding box}
2339
2340 Starting with \PDFTEX\ 1.11, in the \PDF\ image case, you can specify
2341 which page box of the image is to be treated as a final bounding box. If
2342 \Something{pdf box spec} is present, it overrides the default behavior
2343 specified by the \cs{pdfpagebox} parameter, and is overridden in turn by
2344 the (obsolete) \cs{pdfforcepagebox} parameter. This option is irrelevant
2345 for non\hyph \PDF\ inclusions.
2346
2347 \subsubsection{\cs{pdfximage}: \texttt{colorspace}
2348 \Somethingbf{objnumber}}
2349
2350 Starting with \PDFTEX\ 1.21, \cs{pdfximage} supports a \type{colorspace}
2351 keyword followed by an object number, which should be a user\hyph
2352 defined colorspace for the image being included. This is relevant only
2353 for \JPEG\ images. \PNG\ images use \RGB\ palettes, \JBIG2 bi-tonal, and
2354 \PDF\ images have self\hyph contained color space information.
2355
2356 \subsection{\cs{pdfrefximage}}
2357 \pdftexprimitive{\Syntax{\cs{pdfrefximage} \Something{object number}}}
2358
2359 \cs{pdfrefximage} appends a whatsit item to the list being built. When
2360 the whatsit item is searched at shipout time, \PDFTEX\ will write the image
2361 with number \Something{object number} to the \PDF\ output if it has not been
2362 written yet.
2363
2364 \subsection{\cs{pdflastximage}}
2365 \pdftexprimitive{\Syntax{\cs{pdflastximage} \Whatever{read-only integer}}}
2366
2367 \type{\pdflastximage} is the number of the most recently created XObject
2368 image.
2369
2370 \subsection{\cs{pdfximagebbox}}
2371 \pdftexprimitive{\Syntax{\cs{pdfximagebbox} \Something{integer}
2372 \Something{integer} \Whatever{expandable}}}
2373
2374 The dimensions of the bounding box of a \PDF\ image loaded with
2375 \cs{pdfximage} are stored in a table. This primitive returns those
2376 dimensions as follows:
2377
2378 \begin{verbatim}
2379 \pdfximage{afile.pdf}
2380 \pdfximagebbox\pdflastximage 1 % Returns lower-left x
2381 \pdfximagebbox\pdflastximage 2 % Returns lower-left y
2382 \pdfximagebbox\pdflastximage 3 % Returns upper-right x
2383 \pdfximagebbox\pdflastximage 4 % Returns upper-right y
2384 \end{verbatim}
2385
2386 \subsection{\cs{pdflastximagecolordepth}}
2387 \pdftexprimitive{\Syntax{\cs{pdflastximagecolordepth}
2388 \Whatever{read-only integer}}}
2389
2390 The color depth (\type{1} for 1-bit images, \type{2} for 2-bit images,
2391 and so on) of the last image accessed with \cs{pdfximage}.
2392
2393 \subsection{\cs{pdflastximagepages}}
2394 \pdftexprimitive{\Syntax{\cs{pdflastximagepages}
2395 \Whatever{read-only integer}}}
2396
2397 This read-only register returns the highest page number from a file
2398 previously accessed via the \cs{pdfximage} command.
2399 This is useful only for \PDF\ files; it always returns \type{1}
2400 for \PNG, \JPEG, or \JBIGTWO\ files.
2401
2402 \subsection{\cs{pdfimageresolution}}
2403 \pdftexprimitive{\Syntax{\cs{pdfimageresolution} \Whatever{integer}}}
2404
2405 The integer \cs{pdfimageresolution} parameter (given in dots per inch,
2406 dpi) is a last resort value, used only for bitmap (\JPEG, \PNG,
2407 \JBIGTWO) images, but not for \PDF{}s. The priorities are as follows:
2408 Often one image dimension (\type{width} or \type{height}) is stated
2409 explicitly in the \TEX\ file. Then the image is properly scaled so that
2410 the aspect ratio is kept. If both image dimensions are given, the image
2411 will be stretched accordingly, whereby the aspect ratio might get
2412 distorted. If no image dimensions are given in the \TEX\ file, the image
2413 size will be calculated from its width and height in pixels, using the
2414 $x$ and $y$ resolution values normally contained in the image file. If
2415 one of these resolution values is missing or weird (either $<$~0 or
2416 $>$~65535), the \cs{pdfimageresolution} value will be used for both $x$
2417 and $y$ resolution when calculating the image size. And if the
2418 \cs{pdfimageresolution} is zero, a final fallback resolution of 72dpi is
2419 used.
2420
2421 The \cs{pdfimageresolution} is read when \PDFTEX\ creates an image via
2422 \cs{pdfximage}. The given value is clipped to the range $0..65535$
2423 (dpi).
2424
2425 Currently this parameter is used particularly for calculating the
2426 dimensions of \JPEG\ images with \EXIF\ information (unless at least one
2427 dimension is stated explicitly); the resolution values included in
2428 \EXIF\ data are ignored.
2429
2430 \subsection{\cs{pdfpagebox}}
2431 \pdftexprimitive{\Syntax{\cs{pdfpagebox} \Whatever{integer}}}
2432
2433 When \PDF\ files are included, the command \cs{pdfximage} allows the
2434 selection of which \PDF\ page box to use in the optional \Something{pdf
2435 box spec} argument. If that argument isn't present in the command, the
2436 page box defaults to the value of \cs{pdfpagebox} as follows: (1)~media
2437 box, (2)~crop box, (3)~bleed box, (4)~trim box, and (5)~artbox. If
2438 \cs{pdfpagebox} is not set, the default is the crop box.
2439
2440 \subsection{\cs{pdfforcepagebox}}
2441 \pdftexprimitive{\Syntax{\cs{pdfforcepagebox} \Whatever{integer}}}
2442
2443 The integer primitive \cs{pdfforcepagebox} allows globally overriding
2444 the choice of the page box used with \cs{pdfximage}. It takes the same
2445 values as \cs{pdfpagebox}. The command is available starting with
2446 \PDFTEX\ 1.30.0, as a shortened synonym of obsolete
2447 \cs{pdfoptionalwaysusepdfpagebox} instruction, but is itself now
2448 considered obsolete---a combination of \cs{pdfpagebox} and
2449 \Something{pdf box spec} is better.
2450
2451 \subsection{\cs{pdfinclusionerrorlevel}}
2452 \pdftexprimitive{\Syntax{\cs{pdfinclusionerrorlevel} \Whatever{integer}}}
2453
2454 This controls the behavior of \PDFTEX\ when a \PDF\ file is included
2455 which has a newer \PDF\ version than the one specified by
2456 \cs{pdfmajorversion} and \cs{pdfminorversion}. If
2457 \cs{pdfinclusionerrorlevel} is set to~0 (the default), \PDFTEX\ gives a
2458 warning; if 1, \PDFTEX\ raises an error; if negative, no diagnostic at
2459 all is given.
2460
2461 It was originally a shortened synonym of
2462 \cs{pdfoptionpdfinclusionerrorlevel}, which is now obsolete.
2463 \introduced{1.30.0}
2464
2465 \subsection{\cs{pdfimagehicolor}}
2466 \pdftexprimitive{\Syntax{\cs{pdfimagehicolor} \Whatever{integer}}}
2467
2468 This parameter, when set to~1, enables embedding of \PNG\ images with
2469 16~bit wide color channels at their full color resolution. This
2470 embedding mode is defined only from \PDF\ version~1.5 onwards, so the
2471 \cs{pdfimagehicolor} functionality is automatically disabled in \PDFTEX\
2472 if $\cs{pdfminorversion}<5$ and $\cs{pdfmajorversion}=1$; in this case,
2473 each 16~bit color channel is reduced to a width of 8~bits by stripping
2474 the lower 8~bits before embedding. The same stripping happens when
2475 \cs{pdfimagehicolor} is set to~0. If $\cs{pdfmajorversion}=1$ and
2476 $\cs{pdfminorversion}\ge5$, or $\cs{pdfmajorversion}\ge2$, the default
2477 value of \cs{pdfimagehicolor} is~1.
2478
2479 If specified, the parameter must appear before any data is written to
2480 the \PDF\ output. \introduced{1.30.0}
2481
2482 \subsection{\cs{pdfimageapplygamma}}
2483 \pdftexprimitive{\Syntax{\cs{pdfimageapplygamma} \Whatever{integer}}}
2484
2485 This primitive, when set to~1, enables gamma correction while embedding
2486 \PNG\ images, taking the value of the primitive \cs{pdfgamma} as
2487 well as the gamma value embedded in the \PNG\ image into account. When
2488 \cs{pdfimageapplygamma} is set to~0, no gamma correction is
2489 performed.
2490
2491 If specified, the parameter must appear before any data is written to
2492 the \PDF\ output. \introduced{1.30.0}
2493
2494 \subsection{\cs{pdfgamma}}
2495 \pdftexprimitive{\Syntax{\cs{pdfgamma} \Whatever{integer}}}
2496
2497 This primitive defines the `device gamma' for \PDFTEX. Values are in
2498 promilles (same as \cs{mag}). The default value of this primitive
2499 is~1000, defining a device gamma value of~1.0.
2500
2501 If \cs{pdfimageapplygamma} is set to~1, then whenever a \PNG\ image is
2502 included, \PDFTEX\ applies a gamma correction. This correction is based
2503 on the value of the \cs{pdfgamma} primitive and the `assumed device
2504 gamma' that is derived from the value embedded in the actual image. If
2505 no embedded value can be found in the \PNG\ image, then the value of
2506 \cs{pdfimagegamma} is used instead.
2507
2508 If specified, the parameter must appear before any data is written to
2509 the \PDF\ output. \introduced{1.30.0}
2510
2511 \subsection{\cs{pdfimagegamma}}
2512 \pdftexprimitive{\Syntax{\cs{pdfimagegamma} \Whatever{integer}}}
2513
2514 This primitive gives a default `assumed gamma' value for \PNG\ images.
2515 Values are in promilles (same as for \cs{pdfamma}). The default value
2516 of this primitive is~2200, implying an assumed gamma value of~2.2.
2517
2518 When \PDFTEX\ is applying gamma corrections, images that do not have an
2519 embedded `assumed gamma' value are assumed to have been created for a
2520 device with a gamma of 2.2. Experiments show that this default setting
2521 is correct for a large number of images; however, if your images come
2522 out too dark, you probably want to set \cs{pdfimagegamma} to a lower
2523 value, like~1000.
2524
2525 If specified, the parameter must appear before any data is written to
2526 the \PDF\ output. \introduced{1.30.0}
2527
2528 \subsection{\cs{pdfpxdimen}}
2529 \pdftexprimitive{\Syntax{\cs{pdfpxdimen} \Whatever{dimen}}}
2530
2531 While working with bitmap graphics or typesetting electronic documents,
2532 it might be convenient to base dimensions on pixels rather than \TeX's
2533 standard units like \type{pt} or \type{em}. For this purpose, \PDFTEX\
2534 provides an extra unit named \type{px} that takes the dimension given to
2535 the \cs{pdfpxdimen} primitive. For example, to make the unit \type{px}
2536 corresponding to 96dpi pixel density (then $\mbox{1px}=72/96$bp), one
2537 can do the following calculation:
2538
2539 \begin{verbatim}
2540 \pdfpxdimen=1in % 1 dpi
2541 \divide\pdfpxdimen by 96 % 96 dpi
2542 \hsize=1200px
2543 \end{verbatim}
2544
2545 Then \cs{hsize} amounts to 1200~pixels in 96dpi, which is exactly
2546 903.375pt, which \TeX\ rounds to 903.36914pt.
2547
2548 The default value of \cs{pdfpxdimen} is 1.00001bp (for historical
2549 reasons), corresponding to a pixel density of (a few sp off from) 72dpi.
2550 The \LUATEX\ default is 1bp (also a few sp off from 72dpi), so to get
2551 precisely the same behavior in \PDFTEX\ and \LUATEX, set
2552 \cs{pdfpxdimen}\texttt{=1bp}.
2553
2554 This primitive is completely independent of the
2555 \cs{pdfimageresolution} and \cs{pdfpkresolution} parameters.
2556
2557 \introduced{1.30.0} It used to be an integer register that gave the
2558 dimension 1px as number of scaled points, defaulting to 65536 (1px equal
2559 to $\mbox{65536sp}=1$pt). Starting with \PDFTEX\ 1.40.0, \cs{pdfpxdimen}
2560 is now a real dimension parameter.
2561
2562 \subsection{\cs{pdfinclusioncopyfonts}}
2563 \pdftexprimitive{\Syntax{\cs{pdfinclusioncopyfonts} \Whatever{integer}}}
2564
2565 If positive, this parameter tells \PDFTEX\ to include fonts that are
2566 embedded in a \PDF\ file loaded with \cs{pdfximage}, even if those fonts
2567 are also available on disk. Bigger files might be created, but included
2568 \PDF\ files are sure to be embedded with the correct fonts; indeed, the
2569 fonts on disk might be different from the embedded ones, and glyphs
2570 might be missing.
2571
2572 \subsection{\cs{pdfsuppresswarningpagegroup}}
2573 \pdftexprimitive{\Syntax{\cs{pdfsuppresswarningpagegroup}
2574 \Whatever{integer}}}
2575
2576 Ordinarily, \PDFTEX\ gives a warning when more than one included \PDF\
2577 file has a so-called ``page group object'' (\type{/Group}), because only
2578 one can ``win''---that is, be propagated to the page level. Usually
2579 the page groups are identical, but when they are not, the result is
2580 unpredictable. It would be ideal if \PDFTEX\ in fact detected whether
2581 the page groups were the same and only gave the warning in the
2582 problematic case; unfortunately, this is not easy (a patch would be
2583 welcome). Nevertheless, often one observes that there is no actual
2584 problem. Then seeing the warnings on every run is just noise, and can
2585 be suppressed by setting this parameter to a positive number.
2586 \introduced{1.40.15}
2587
2588 \section{Annotations}
2589
2590 \PDF\ 1.4 provides four basic kinds of annotations:
2591
2592 \begin{itemize}
2593 \item hyperlinks, general navigation
2594 \item text clips (notes)
2595 \item movies
2596 \item sound fragments
2597 \end{itemize}
2598
2599 The first type differs from the other three in that there is a
2600 designated area involved on which one can click, or when moved over some
2601 action occurs. \PDFTEX\ is able to calculate this area, as we will see
2602 later. All annotations can be supported using the next two general
2603 annotation primitives.
2604
2605 \subsection{\cs{pdfannot}}
2606 \pdftexprimitive{\Syntax{\cs{pdfannot} \Something{annot type spec}
2607 \Modelist{h, v, m}}}
2608
2609 \noindent\Syntax{
2610 \Something{annot type spec} \Means
2611 \Literal{reserveobjnum}
2612 \Or\Next
2613 \Optional{\Literal{useobjnum} \Something{number}}
2614 \Optional{\Something{rule spec}}
2615 \Something{general text}
2616 }
2617
2618 \label{pdfannot}
2619 This command appends a whatsit item corresponding to an annotation to
2620 the list being built. The dimensions of the annotation can be controlled
2621 via the \Something{rule spec}. The default values are ``running'' for
2622 all width, height and depth. When an annotation is written out, running
2623 dimensions will take the corresponding values from the box containing
2624 the whatsit item representing the annotation. The \Something{general
2625 text} is inserted as raw \PDF\ code to the contents of annotation. The
2626 annotation is written only if the corresponding whatsit item is searched
2627 at shipout time.
2628
2629 \subsection{\cs{pdflastannot}}
2630 \pdftexprimitive{\Syntax{\cs{pdflastannot} \Whatever{read-only integer}}}
2631
2632 This primitive returns the object number of the last annotation created by
2633 \cs{pdfannot}. These two primitives allow users to create any annotation
2634 that cannot be created by \cs{pdfstartlink} (see below).
2635
2636 \section{Destinations and links}
2637 \label{sec.linking}
2638
2639 The first type of annotation (hyperlinks and navigation), mentioned
2640 above, is implemented by three primitives. The first one is used to
2641 define a specific location as being referred to. This location is tied
2642 to the page, not the exact location on the page. The main reason for
2643 this is that \PDFTEX\ maintains a dedicated list of these annotations,
2644 and more when optimized, for the sole purpose of speed.
2645
2646 \subsection{\cs{pdfdest}}
2647 \pdftexprimitive{\Syntax{\cs{pdfdest} \Something{dest spec}
2648 \Modelist{h, v, m}}}
2649
2650 \noindent\Syntax{
2651 \Something{dest spec} \Means
2652 \Optional{\Literal{struct} \Something{number}}
2653 \OneOf{\Something{numid} \Or \Something{nameid}}
2654 \Something{dest type}
2655 \newline
2656 \Something{dest type} \Means
2657 \Literal{xyz} \Optional{\Literal{zoom} \Something{number}}
2658 \Next
2659 \Or \Literal{fitr} \Something{rule spec}
2660 \Or \Literal{fit}
2661 \Or \Literal{fith}
2662 \Or \Literal{fitv}
2663 \Or \Literal{fitb}
2664 \Or \Literal{fitbh}
2665 \Or \Literal{fitbv}
2666 }
2667
2668 This primitive appends a whatsit item which establishes a destination
2669 for links and bookmark outlines; the link is identified by either a
2670 number or a symbolic name, and the way the viewer is to display the page
2671 is specified in \Something{dest spec}, as described in this table:
2672
2673 \begin{smalltable}
2674 \begin{tabular}{ll}
2675 \bf keyword & \bf meaning \cr
2676 \tt struct \Optional{\Something{number}}
2677 & create structure destination (see below) \cr
2678 \tt xyz \Optional{zoom \Something{number}}
2679 & goto the current position (see below) \cr
2680 \tt fitr \Something{rule spec}
2681 & fit according to \Something{rule spec} \cr
2682 \tt fit & fit the page in the window \cr
2683 \tt fith & fit the width of the page \cr
2684 \tt fitv & fit the height of the page \cr
2685 \tt fitb & fit the \type{BoundingBox} of the page \cr
2686 \tt fitbh & fit the width of \type{BoundingBox} of the page \cr
2687 \tt fitbv & fit the height of \type{BoundingBox} of the page \cr
2688 \end{tabular}
2689 \end{smalltable}
2690
2691 If \Literal{struct} \Something{number} is used, a structure destination
2692 is created instead of a regular destination, referring to the structure
2693 element defined in object \Something{number}. Structure destinations use
2694 a separate namespace and therefore may have the same identifiers as a
2695 regular destination.
2696
2697 The \Literal{xyz} keyword can optionally be followed by \Literal{zoom}
2698 \Something{integer} to provide a fixed zoom\hyph in. The
2699 \Something{integer} is used like a \TEX\ magnification value, \ie\ 1000
2700 is the normal page view. When \Literal{zoom} \Something{integer} is
2701 given, the zoom factor changes to 0.001 of the \Something{integer}
2702 value, otherwise the current zoom factor is kept unchanged.
2703
2704 The destination is written out only if the corresponding whatsit item is
2705 searched at shipout.
2706
2707 \newpage
2708 \subsection{\cs{pdfstartlink}}
2709 \pdftexprimitive{\Syntax{\cs{pdfstartlink}
2710 \Optional{\Something{rule spec}}
2711 \Optional{\Something{attr spec}}
2712 \Something{action spec}
2713 \Modelist{h, m}
2714 }}
2715
2716 \noindent \Syntax{
2717 \Something{rule spec} \Means
2718 (\Literal{width} \Or \Literal{height} \Or \Literal{depth})
2719 \Something{dimen} \Optional{\Something{rule spec}}
2720 \newline
2721 \Something{attr spec} \Means
2722 \Literal{attr} \Something{general text}
2723 \newline
2724 \Something{action spec} \Means
2725 \Literal{user} \Something{user-action spec}
2726 \Next\Or \Literal{goto} \Something{goto-action spec}
2727 \Next\Or \Literal{thread} \Something{thread-action spec}
2728 }
2729
2730 \noindent (The syntax for the three \Something{action-spec}s are given
2731 in the subsections below.)\aftersyntax
2732
2733 General points about PDF links:
2734
2735 \begin{itemize}
2736 \item An invocation of \cs{pdfstartlink} must be terminated by
2737 \cs{pdfendlink}.
2738
2739 \item \cs{pdfstartlink} inserts a whatsit item corresponding to the start of
2740 a hyperlink. Another whatsit representing the end of the hyperlink is
2741 inserted by \cs{pdfendlink}.
2742
2743 \item A \cs{pdfstartlink} and its corresponding \cs{pdfendlink} must be
2744 at the same level of box nesting.
2745
2746 \item The hyperlink is written to the final output only if the
2747 corresponding whatsit is searched at shipout time.
2748
2749 \item A hyperlink with running width can be multi\hyph line or even
2750 multi\hyph page, in which case all horizontal boxes at the same nesting
2751 level as the boxes containing \cs{pdfstartlink} and \cs{pdfendlink} will
2752 be treated as part of the hyperlink.
2753
2754 \item While all graphics and text in a \PDF\ document have relative
2755 positions, annotations have internally hard\hyph coded absolute
2756 positions. Again, this is for the sake of speed optimization. The main
2757 disadvantage is that these annotations do \emph{not} obey
2758 transformations issued by \type{\pdfliteral}.
2759
2760 \item The \Something{action spec} specifies the action that should be
2761 performed when the hyperlink is activated. The data inside an
2762 \Something{action spec} is typically PostScript dictionaries and
2763 variable settings, as defined by the \PDFReference.
2764
2765 \end{itemize}
2766
2767 \subsubsection{\cs{pdfstartlink}: \Somethingbf{rule spec} for link dimensions}
2768
2769 The dimensions of the link are handled in the same way as \cs{pdfannot}
2770 (p.~\pageref{pdfannot}), including using the \Something{rule spec} if
2771 specified.
2772
2773 \subsubsection{\cs{pdfstartlink}: \Somethingbf{attr spec} for link attributes}
2774
2775 The \Something{attr spec} allows specifying numerous additional
2776 attributes for the link, which are explained in the \PDFReference, and
2777 won't be repeated here. Typically, the attributes specify the color and
2778 thickness of any border around the link. As a basic example:\\
2779 %
2780 \verb|attr{/C [0.9 0 0] /Border [0 0 2]}|
2781 %
2782 \\specifies a color (in \RGB) of dark red, and a border thickness of 2
2783 (PostScript) points.
2784
2785 \subsubsection{\cs{pdfstartlink}: \type{user} \Somethingbf{user-action spec}
2786 for user-defined actions}
2787
2788 \Syntax{
2789 \Something{user-action spec} \Means
2790 \Something{general text}
2791 }
2792
2793 A \Something{user-action spec} (\type{user{...}}) performs a user\hyph
2794 defined action, such as opening a url, whether in the current or another
2795 document; see the ``Actions'' section in the \PDFReference, \S12.6.
2796 Here's an example for making a link to an external url:
2797 \begin{verbatim}
2798 \pdfstartlink
2799 attr{/Border [0 0 0]}
2800 user{/Subtype /Link
2801 /A << /S /URI /URI (https://tug.org/) >>}%
2802 TUG home page%
2803 \pdfendlink
2804 \end{verbatim}
2805
2806 \noindent The \type{/Border} value in the \type{attr} line eliminates
2807 the box around the link displayed by viewers by default.
2808
2809 \subsubsection{\cs{pdfstartlink}: \type{goto} \Somethingbf{goto-action spec}
2810 for jump actions}
2811
2812 \noindent\Syntax{
2813 \Something{goto-action spec} \Means
2814 \Optional{\Something{goto-action struct spec}} \Something{numid}
2815 \Next\Or \Optional{\Something{file spec}} \Optional{\Something{goto-action struct spec}} \Something{nameid}
2816 \Next\Or \Optional{\Something{file spec}} \Optional{\Something{goto-action struct spec}}
2817 \Optional{\Something{page spec}} \Something{general text}
2818 \Next\Or \Something{file spec} \Optional{\Something{goto-action struct spec}}
2819 \Next\qquad \Optional{
2820 \Something{nameid}
2821 \Or \Something{page spec} \Something{general text}}
2822 \Next\qquad \Something{newwindow spec}
2823 \newline
2824 \Something{goto-action struct spec} \Means
2825 \Literal{struct} \OneOf{\Something{numid} \Or \Something{nameid}
2826 \Or \Something{general text}}
2827 \newline
2828 \Something{newwindow spec} \Means
2829 \Literal{newwindow} \Or \Literal{nonewwindow}
2830 \newline
2831 \Something{file spec} \Means
2832 \Literal{file} \Something{general text}
2833 \newline
2834 \Something{numid} \Means
2835 \Literal{num} \Something{number}
2836 \newline
2837 \Something{nameid} \Means
2838 \Literal{name} \Something{general text}
2839 \newline
2840 \Something{page spec} \Means
2841 \Literal{page} \Something{number}
2842 }
2843
2844 A \Something{goto-action spec} (\type{goto...}) performs various
2845 goto actions, and is by far the most complex action.
2846
2847 \begin{itemize}
2848 \item The \Something {numid} and \Something{nameid} alternatives (the
2849 first two) specify a destination identifier in the current or given
2850 file.
2851
2852 \item The \Something{page spec} (third) alternative specifies a page
2853 number for the destination. Here, the final \Something{general text}
2854 defines the zoom factor.
2855
2856 \item If the initial \Something{file spec} is given, the destination
2857 refers to that file. The \Something{file spec} is required if the
2858 \Something{newwindow spec} is given, which specifies whether or not the
2859 file should be opened in a new window (the default is
2860 browser-dependent). A \Something{file spec} can be either a
2861 \type{(}\Something{string}\type{)} or a
2862 \type{<<}\Something{dictionary}\type{>>}.
2863
2864 \item If a \Something{goto-action spec} contains a
2865 \Something{goto-action struct spec} (\type{struct...}), then a structure
2866 destination is referenced in addition to the regular destination. The
2867 form with \Something{general text} is used if and only if the initial
2868 \Something{file spec} is present; then the \Something{general text}
2869 should expand to a literal \PDF\ dictionary describing a structure
2870 destination. Otherwise, the \Something{numid} or \Something{nameid}
2871 directly after the \Literal{struct} keyword identify a destination which
2872 must have been created with \cs{pdfdest} \Literal{struct}\unskip.
2873
2874 \end{itemize}
2875
2876 \subsubsection{\cs{pdfstartlink}: \type{thread}
2877 \Somethingbf{thread-action spec} for article threads}
2878
2879 \noindent\Syntax{
2880 \Something{thread-action spec} \Means
2881 \Optional{\Something{file spec}} \Something{numid}
2882 \Or \Optional{\Something{file spec}} \Something{nameid}
2883 }
2884
2885 A \Something{thread-action spec} (\type{thread ...}) performs article
2886 thread reading. The thread identifier, \Something{numid} or
2887 \Something{nameid}, is analogous to the destination identifier described
2888 above. A thread in another \PDF\ file can be referenced by specifying a
2889 \Something{file spec}.
2890
2891 \subsection{\cs{pdfendlink}}
2892 \pdftexprimitive{\Syntax{\cs{pdfendlink} \Modelist{h, m}}}
2893
2894 This primitive ends a link started with \cs{pdfstartlink}. All text
2895 between \cs{pdfstartlink} and \cs{pdfendlink} will be treated as part
2896 of this link. \PDFTEX\ may break the result across lines (or pages), in which
2897 case it will make several links with the same content.
2898
2899 \subsection{\cs{pdflastlink}}
2900 \pdftexprimitive{\Syntax{\cs{pdflastlink} \Whatever{read-only integer}}}
2901
2902 This primitive returns the object number of the last link created by
2903 \cs{pdfstartlink} (analogous to \cs{pdflastannot}).
2904 \introduced{1.40.0}
2905
2906 \subsection{\cs{pdflinkmargin}}
2907 \pdftexprimitive{\Syntax{\cs{pdflinkmargin} \Whatever{dimen}}}
2908
2909 This dimension parameter specifies the margin of the box representing
2910 a hyperlink and is read when a page containing hyperlinks is shipped out.
2911
2912 \subsection{\cs{pdfdestmargin}}
2913 \pdftexprimitive{\Syntax{\cs{pdfdestmargin} \Whatever{dimen}}}
2914
2915 Margin added to the dimensions of the rectangle around the destinations.
2916
2917 \subsection{\cs{pdfsuppresswarningdupdest}}
2918 \pdftexprimitive{\Syntax{\cs{pdfsuppresswarningdupdest} \Whatever{integer}}}
2919
2920 Ordinarily, \PDFTEX\ gives a warning when the same destination is used
2921 more than once. However, due to problematic macro packages, sometimes a
2922 document may end up producing the warning through no fault of its own,
2923 and fixing the macros may not be feasible. Then seeing the warnings on
2924 every run is just noise, and can be suppressed by setting this parameter
2925 to a positive number. \introduced{1.40.13}
2926
2927 \subsection{\cs{pdfrunninglinkon}, \cs{pdfrunninglinkoff}}
2928 \pdftexprimitive{\Syntax{\cs{pdfrunninglinkoff}}}
2929 \pdftexprimitive{\Syntax{\cs{pdfrunninglinkon}}}
2930
2931 These commands create corresponding whatsit items which turn off/on
2932 generation of running links. Their typical usage is to turn off
2933 generation of running links in the header or footer of a page.
2934 Generation of running links is on when the shipout routine begins.
2935
2936 The generation of running links works roughly like this: \PDFTEX\ keeps
2937 a stack of links created by \cs{pdfstartlink}, called
2938 \type{pdf_link_stack}. When writing out an hbox to \PDF, \PDFTEX\ checks
2939 if the nesting level of the box is the same as the nesting level of the
2940 top entry in \type{pdf_link_stack}; if so, that box would become a link,
2941 too.
2942
2943 The whatsit items created by the above primitives turn off/on a flag
2944 which controls if a hbox being shipped can become a link, in addition to
2945 the previous condition.
2946
2947 Thus, the commands must be inserted before the hbox in question. For example:
2948
2949 \begin{verbatim}
2950 % (1) good:
2951 \hbox{\pdfrunninglinkoff
2952 \hbox{text that would become a link otherwise}
2953 }
2954
2955 % (2) bad:
2956 \hbox{\pdfrunninglinkoff text that would become a link otherwise}
2957 % too late; \pdfrunninglinkoff must be inserted before the box
2958 \end{verbatim}
2959
2960 \section{Bookmarks}
2961
2962 \subsection{\cs{pdfoutline}}
2963 \pdftexprimitive{\Syntax{\cs{pdfoutline}
2964 \Optional{\Something{attr spec}}
2965 \Something{action spec}
2966 \Optional{\Literal{count} \Something{integer}}
2967 \Something{general text}
2968 \Modelist{h, v, m}
2969 }}
2970
2971 This primitive creates an outline (or bookmark) entry. The first
2972 parameter, \Something{attr spec}, specifies the action to be taken, and
2973 is the same as that allowed for \type{\pdfstartlink}.
2974
2975 The \Literal{count} \Something{integer} specifies the number of direct
2976 subentries under this entry; specify~0 or omit the clause if this entry
2977 has no subentries. If the \Something{integer} is negative, then all
2978 subentries will be closed and the absolute value of this number
2979 specifies the number of subentries.
2980
2981 The \Something{general text} is what will be shown in the outline
2982 window. The outline is written to the \PDF\ output immediately.
2983
2984 \section{Article threads}
2985
2986 \subsection{\cs{pdfthread}}
2987 \pdftexprimitive{\Syntax{\cs{pdfthread} \Optional{\Something{rule spec}}
2988 \Optional{\Something{attr spec}} \Something{id spec} \Modelist{h, v, m}}}
2989
2990 Defines a bead within an article thread. Thread beads with same
2991 identifiers (spread across the document) will be joined together.
2992
2993 \subsection{\cs{pdfstartthread}}
2994 \pdftexprimitive{\Syntax{\cs{pdftstartthread}
2995 \Optional{\Something{rule spec}}
2996 \Optional{\Something{attr spec}}
2997 \Something{id spec} \Modelist{v, m}}}
2998
2999 This uses the same syntax as \cs{pdfthread}, apart that it must be
3000 followed by a \cs{pdfendthread}. \cs{pdfstartthread} and the
3001 corresponding \cs{pdfendthread} must end up in vboxes with the same
3002 nesting level; all vboxes between them will be added into the thread.
3003
3004 In the output routine, if there are other newly created boxes which have
3005 the same nesting level as the vbox(es) containing \cs{pdfstartthread}
3006 and \cs{pdfendthread}, they will be also added into the thread, which is
3007 probably not what you want. To avoid such undesired behavior, it's often
3008 enough to wrap boxes that shouldn't belong to the thread by a box to
3009 change their box nesting level.
3010
3011 \subsection{\cs{pdfendthread}}
3012 \pdftexprimitive{\Syntax{\cs{pdfendthread} \Modelist{v, m}}}
3013
3014 This ends an article thread started before by \cs{pdfstartthread}.
3015
3016 \subsection{\cs{pdfthreadmargin}}
3017 \pdftexprimitive{\Syntax{\cs{pdfthreadmargin} \Whatever{dimen}}}
3018
3019 Specifies a margin to be added to the dimensions of a bead within
3020 an article thread.
3021
3022 \section{Literals and specials}
3023
3024 \subsection{\cs{pdfliteral}}
3025 \pdftexprimitive{\Syntax{\cs{pdfliteral}
3026 \Optional{\Literal{shipout}}
3027 \Optional{\Literal{direct} \Or \Literal{page}}
3028 \Something{general text}
3029 \Modelist{h, v, m}
3030 }}
3031
3032 Analogous to \cs{special} in the original \TEX, this command inserts
3033 raw \PDF\ code into the output, appending a whatsit item to the list
3034 being built. This allows support of color and text transformation, among
3035 other things.
3036
3037 By default, \Something{general text} is expanded immediately, when the
3038 whatsit item is created, as with \cs{special}. Starting with \PDFTEX\
3039 1.40.25, the optional keyword \Literal{shipout} can be used to delay
3040 expansion of \Something{general text} until the whatsit item is shipped
3041 out, as with non-\cs{immediate} \cs{write}.
3042
3043 Normally, \PDFTEX\ ends a text section in the \PDF\ output and sets the
3044 transformation matrix to the current location on the page before
3045 inserting \Something{general text}; this can be turned off by
3046 giving the optional keyword \Literal{direct}.
3047
3048 Starting with version 1.30.0, \PDFTEX\ supports the keyword \type{page}
3049 in addition to \type{direct}. Both modify the default behavior of
3050 \cs{pdfliteral}, avoiding translation of the coordinate space before
3051 inserting the literal code. The difference is that the \type{page}
3052 keyword instructs \PDFTEX\ to close a \type{BT...ET} text block before
3053 inserting anything. This means that the literal code inserted refers to
3054 the \PDF\ origin (lower-left corner of the page) and can be safely
3055 enclosed with \type{q...Q}. In contrast, using \type{q...Q} operators
3056 inside \cs{pdfliteral} with the \type{direct} keyword will produce
3057 corrupted \PDF\ output, as the \PDF\ standard doesn't allow doing
3058 anything like this within a \type{BT...ET} block.
3059
3060 \subsection{\cs{special}}
3061 \pdftexprimitive{\Syntax{\cs{special} \Lbrace\Literal{pdf:}
3062 \Something{text}\Rbrace}}
3063
3064 This is equivalent to \InlineSyntax{\cs{pdfliteral}
3065 \Lbrace\Something{text}\Rbrace}.
3066
3067 \subsection{\cs{special\ direct}}
3068 \pdftexprimitive{\Syntax{\cs{special} \Lbrace\Literal{pdf:direct:}
3069 \Something{text}\Rbrace}}
3070
3071 This is equivalent to \InlineSyntax{\cs{pdfliteral} \Literal{direct}
3072 \Lbrace\Something{text}\Rbrace}.
3073
3074 \subsection{\cs{special\ page}}
3075 \pdftexprimitive{\Syntax{\cs{special} \Lbrace\Literal{pdf:page:}
3076 \Something{text}\Rbrace}}
3077
3078 This is equivalent to \InlineSyntax{\cs{pdfliteral} \Literal{page}
3079 \Lbrace\Something{text}\Rbrace}.
3080
3081 \subsection{\cs{special\ shipout}}
3082 \pdftexprimitive{\Syntax{\cs{special} \Optional{\Literal{shipout}}
3083 \Lbrace\Something{text}\Rbrace}}
3084
3085 Starting with version 1.40.25, \PDFTEX\ extends the \cs{special}
3086 primitive to support the optional keyword \Literal{shipout}. This delays
3087 expansion of \Something{text} until the page is shipped out, as with a
3088 non-\cs{immediate} \cs{write}. By default, \Something{text} is expanded
3089 immediately.
3090
3091 \InlineSyntax{\cs{special} \Literal{shipout} \Lbrace \Literal{pdf:}
3092 \Something{text}\Rbrace} is equivalent to \InlineSyntax{\cs{pdfliteral}
3093 \Literal{shipout} \Lbrace \Something{text}\Rbrace}.
3094
3095 \section{Strings}
3096
3097 \subsection{\cs{pdfescapestring}}
3098 \pdftexprimitive{\Syntax{\cs{pdfescapestring} \Something{general text}
3099 \Whatever{expandable}}}
3100
3101 Starting with version 1.30.0, \PDFTEX\ provides a mechanism for
3102 converting a general text into \PDF\ string. Many characters that may be
3103 needed inside such a text (notably parentheses), have a special meaning
3104 inside a \PDF\ string object and thus, can't be used literally. The
3105 primitive replaces each special \PDF\ character by its literal
3106 representation by inserting a backslash before that character. Some
3107 characters (\eg\ space) are also converted into 3\hyph digit octal
3108 number. For example, \verb|\pdfescapestring{Text (1)}| will be expanded
3109 to \type{Text\040\(1\)}. This ensures a literal interpretation of the
3110 text by the \PDF\ viewer. \introduced{1.30.0}
3111
3112 \subsection{\cs{pdfescapename}}
3113 \pdftexprimitive{\Syntax{\cs{pdfescapename} \Something{general text}
3114 \Whatever{expandable}}}
3115
3116 Analogous to \cs{pdfescapestring}, \cs{pdfescapename} replaces each
3117 special \PDF\ character inside the general text by its hexadecimal
3118 representation preceded by a \type{#} character. This ensures the proper
3119 interpretation of the text if used as a \PDF\ name object. In example,
3120 \verb|Text (1)| will be replaced by \type{Text#20#281#29}.
3121 \introduced{1.30.0}
3122
3123 \subsection{\cs{pdfescapehex}}
3124 \pdftexprimitive{\Syntax{\cs{pdfescapehex} \Something{general text}
3125 \Whatever{expandable}}}
3126
3127 This command converts each character of \Something{general text} into its
3128 hexadecimal representation. Each character of the argument becomes a pair of
3129 hexadecimal digits. \introduced{1.30.0}
3130
3131 \subsection{\cs{pdfunescapehex}}
3132 \pdftexprimitive{\Syntax{\cs{pdfunescapehex} \Something{general text}
3133 \Whatever{expandable}}}
3134
3135 This command treats each character pair of \Something{general text} as
3136 a hexadecimal number and returns the corresponding characters.
3137 \introduced{1.30.0}
3138
3139 \subsection{\cs{pdfstrcmp}}
3140 \pdftexprimitive{\Syntax{\cs{pdfstrcmp} \Something{general text}
3141 \Something{general text} \Whatever{expandable}}}
3142
3143 This command compares two strings and expands to \type{0} if the strings
3144 are equal, to \type{-1} if the first string ranks before the second, and
3145 to \type{1} otherwise. \introduced{1.30.0}
3146
3147 \subsection{\cs{pdfmatch}}
3148 \pdftexprimitive{\Syntax{\cs{pdfmatch} \Optional{\Literal{icase}}
3149 \Optional{\Literal{subcount} \Something{integer}} \Something{general text}
3150 \Something{general text} \Whatever{expandable}}}
3151
3152 This command implements pattern matching, using \POSIX\ extended regular
3153 expression syntax. The first \Something{general text} is a pattern and
3154 the second is a string. The command expands to \type{-1} if the pattern
3155 is invalid, to \type{0} if no match is found, and to \type{1} if a match
3156 is found. With the \type{icase} option, the matching is
3157 case-insensitive. The \type{subcount} option sets the size of the table
3158 storing the found (sub)patterns; its default is 10. \introduced{1.30.0}
3159
3160 \subsection{\cs{pdflastmatch}}
3161 \pdftexprimitive{\Syntax{\cs{pdflastmatch} \Something{integer}
3162 \Whatever{expandable}}}
3163
3164 The matches found with \cs{pdfmatch} are stored in a table. This command
3165 returns the entry for match \Something{integer}, in the format
3166 \Something{position}\type{->}\Something{string}; \Something{position} is
3167 the position of the match (starting at zero) or \type{-1} if no match
3168 was found, and \Something{string} is the matched substring.
3169
3170 Entry~0 contains the match as a whole; the subsequent entries contain
3171 submatches corresponding to the subpatterns, up to \type{subcount-1}.
3172
3173 If \Something{integer} is less than zero, an error is given.
3174
3175 For instance:
3176
3177 \begin{verbatim}
3178 \pdfmatch subcount 3 {ab(cd)*ef(gh)(ij)}{abefghij}
3179 \pdflastmatch0 % "0->abefghij"
3180 \pdflastmatch1 % "-1->"
3181 \pdflastmatch2 % "4->gh"
3182 \pdflastmatch3 % "-1->"
3183 \end{verbatim}
3184
3185 Entry~1 is empty because no match was found for \type{cd}, and entry~3
3186 is empty because it exceeds the table's size as set by \type{subcount}.
3187 \introduced{1.30.0}
3188
3189 \section{Numbers}
3190
3191 \subsection{\cs{ifpdfabsnum}, \cs{ifpdfabsdim}}
3192 \pdftexprimitive{\Syntax{\cs{ifpdfabsnum} \Whatever{expandable}}}
3193 \pdftexprimitive{\Syntax{\cs{ifpdfabsdim} \Whatever{expandable}}}
3194
3195 This conditional works like the standard \cs{ifnum} (resp.\ \cs{ifdim}),
3196 except that it compares absolute values of numbers (dimensions).
3197 Although it seems to be a trivial shortcut for a couple of regular
3198 \cs{if} tests, as primitives they are considerably simpler and faster to
3199 use. \introduced{1.40.0}
3200
3201 \subsection{\cs{pdfnormaldeviate}}
3202 \pdftexprimitive{\Syntax{\cs{pdfnormaldeviate} \Whatever{expandable}}}
3203
3204 Generate a normally-distributed random integer with a mean of~0 and
3205 standard deviation 65536. That is, about 68\% of the time, the result
3206 will be between $-65536$ and $65536$ (one standard deviation away from
3207 the mean). About 95\% of results will be within two standard deviations,
3208 and 99.7\% within three. This primitive expands to a list of tokens.
3209 \introduced{1.30.0}
3210
3211 \subsection{\cs{pdfuniformdeviate}}
3212 \pdftexprimitive{\Syntax{\cs{pdfuniformdeviate} \Something{number}
3213 \Whatever{expandable}}}
3214
3215 Generate a uniformly-distributed random integer value between 0
3216 (inclusive) and \Something{number} (exclusive). This primitive expands
3217 to a list of tokens. \introduced{1.30.0}
3218
3219 \subsection{\cs{pdfrandomseed}}
3220 \pdftexprimitive{\Syntax{\cs{pdfrandomseed} \Whatever{read-only integer}}}
3221
3222 You can use \cs{pdfrandomseed} to query the current seed value, so you
3223 can \eg\ write the value to the log file. The initial value of the seed
3224 is derived from the system time, and is not more than 1\,000\,999\,999
3225 (this ensures that the value can be used with commands like \cs{count}).
3226 \introduced{1.30.0}
3227
3228 \subsection{\cs{pdfsetrandomseed}}
3229 \pdftexprimitive{\Syntax{\cs{pdfsetrandomseed} \Something{number}}}
3230
3231 Set the random seed (\cs{pdfrandomseed}) to a specific value,
3232 allowing you to replay sequences of semi-randoms at a later moment.
3233 \introduced{1.30.0}
3234
3235 \section{Timekeeping}
3236
3237 \subsection{\cs{pdfelapsedtime}}
3238 \pdftexprimitive{\Syntax{\cs{pdfelapsedtime} \Whatever{read-only integer}}}
3239
3240 Return a number that represents the time elapsed from the moment of the
3241 start of the run. The elapsed time is returned in `scaled seconds',
3242 meaning seconds divided by 65536, \eg\ \PDFTEX\ has run for
3243 \the\pdfelapsedtime\ `scaled seconds' when this paragraph was typeset.
3244 The primitive will never return a value greater than the highest number
3245 available in \TeX: if the time exceeds 32767 seconds, the constant value
3246 $2^{31}-1$ will be returned. \introduced{1.30.0}
3247
3248 \subsection{\cs{pdfresettimer}}
3249 \pdftexprimitive{\Syntax{\cs{pdfresettimer}}}
3250
3251 Reset the internal timer so that \cs{pdfelapsedtime}
3252 starts returning the scaled seconds from~0 again. \introduced{1.30.0}
3253
3254 \section{Files}
3255
3256 \subsection{\cs{pdffiledump}}
3257 \pdftexprimitive{\Syntax{\cs{pdffiledump}
3258 \Optional{\Literal{offset} \Something{integer}}
3259 \Optional{\Literal{length} \Something{integer}}
3260 \Something{general text} \Whatever{expandable}}}
3261
3262 Expands to the dump of the first \type{length} \Something{integer} bytes
3263 of the file specified by \Something{general text}, in uppercase
3264 hexadecimal format (same as \cs{pdfescapehex}), starting at offset
3265 \type{offset}~\Something{number}, or the beginning of the file if
3266 \type{offset} is zero or not specified. If \type{length} is not given,
3267 the default is zero, so expands to nothing. Both \Something{integer}s
3268 must be $\ge0$. For example, the first ten bytes of the source of this
3269 manual are {\tt\pdffiledump length 10 {./\jobname}}.
3270 \introduced{1.30.0}
3271
3272 \subsection{\cs{pdffilesize}}
3273 \pdftexprimitive{\Syntax{\cs{pdffilesize} \Something{general text}
3274 \Whatever{expandable}}}
3275
3276 Expands to the size of the file specified by \Something{general text},
3277 \eg\ {\tt \pdffilesize{./\jobname}} for the source of this manual.
3278 \introduced{1.30.0}
3279
3280 \subsection{\cs{pdfmdfivesum\ file}}
3281 \pdftexprimitive{\Syntax{\cs{pdfmdfivesum}
3282 \Optional{\Literal{file}}
3283 \Something{general text} \Whatever{expandable}}}
3284
3285 If the keyword \type{file} is given, expands to the \MDFIVE\ checksum of
3286 the \Something{general text} in uppercase hexadecimal format (same as
3287 \cs{pdfescapehex}). Without \type{file}, expands to the \MDFIVE\ of the
3288 \Something{general text} taken as a string. For example, the \MDFIVE\ of
3289 the source for this manual is {\tt \pdfmdfivesum file{./\jobname}}.
3290 \introduced{1.30.0}
3291
3292 \subsection{\cs{pdffilemoddate}}
3293 \pdftexprimitive{\Syntax{\cs{pdffilemoddate} \Something{general text}
3294 \Whatever{expandable}}}
3295
3296 Expands to the modification date of file specified by \Something{general
3297 text}, in the same format as for \cs{pdfcreationdate}, \eg\ {\tt
3298 \pdffilemoddate {./\jobname}} for the source of this manual. As of
3299 \PDFTEX\ 1.40.20, if the \type{SOURCE_DATE_EPOCH} and
3300 \type{FORCE_SOURCE_DATE} environment variables are both set,
3301 \cs{pdffilemoddate} returns a value in UTC, ending in \type{Z}.
3302 \introduced{1.30.0}
3303
3304 \subsection{\cs{input}}
3305 \pdftexprimitive{\Syntax{\cs{input} \Something{general text}
3306 \Whatever{expandable}}}
3307
3308 As of \TEXLIVE\ 2020, the \cs{input} primitive in all \TEX\ engines,
3309 including \PDFTEX, now also accepts a group-delimited filename argument,
3310 as a system-dependent extension, as in
3311 \cs{input}\Lbrace\type{foo.tex}\Rbrace. The standard usage of \cs{input}
3312 with a space/token-delimited filename is completely unchanged.
3313
3314 This group-delimited argument was previously implemented in Lua\TEX; now
3315 it is available in all engines. \ASCII\ double quote characters
3316 (\type{"}) are removed from the filename, but it is otherwise left
3317 unchanged after tokenization.
3318
3319 This extension is unlike most others in that it affects a primitive in
3320 standard \TEX\ (\cs{input}), rather than being related to a new
3321 primitive, command line option, etc. This is allowed because additional
3322 methods of recognizing filenames are explicitly mentioned in
3323 \type{tex.web} as acceptable system-dependent extensions.
3324
3325 Incidentally, this does not directly affect \LATEX's \cs{input}
3326 command, as that is a macro redefinition of the standard \cs{input}
3327 primitive.
3328
3329 \introduced{1.40.21}
3330
3331 \section{Color stack}
3332
3333 \PDFTEX\ 1.40.0 introduced color stack support; more generally, stacks
3334 of any graphic state.
3335
3336 \subsection{\cs{pdfcolorstackinit}}
3337 \pdftexprimitive{\Syntax{\cs{pdfcolorstackinit} \Optional{\Literal{page}}
3338 \Optional{\Literal{direct}} \Something{general text} \Whatever{expandable}}}
3339
3340 The primitive initializes a new graphic stack and returns its number.
3341 The optional \Literal{page} keyword instructs \PDFTEX\ to restore the
3342 graphic at the beginning of every new page. The optional
3343 \Literal{direct} keyword has the same effect as for \cs{pdfliteral}
3344 primitive. \introduced{1.40.0}
3345
3346 \subsection{\cs{pdfcolorstack}}
3347 \pdftexprimitive{\Syntax{\cs{pdfcolorstack} \Something{stack number}
3348 \Something{stack action} \Something{general text}}}
3349 \noindent \Something{stack action} \Means
3350 \Literal{set} \Or \Literal{push} \Or \Literal{pop} \Or \Literal{current}
3351
3352 The command operates on the stack of a given \Something{stack number}.
3353 If \Something{stack action} is:
3354
3355 \begin{description}
3356 \item[\Literal{push}:] the new value in \Something{general text} is inserted at
3357 the top of the graphic stack and becomes the current stack value.
3358
3359 \item[\Literal{pop}:] the top value is removed from the stack and the new
3360 top value becomes the top of the stack.
3361
3362 \item[\Literal{set}:] the current value is replaced with
3363 \Something{general text}, without changing the stack size.
3364
3365 \item[\Literal{current}:] the current stack value is return without
3366 modifying the stack.
3367 \end{description}
3368
3369 \introduced{1.40.0}
3370
3371 \section{Transformations}
3372
3373 Since the content of \cs{pdfliteral} is not interpreted, any
3374 transformation inserted directly into the content stream, as well as
3375 saving and restoring the current transformation matrix, will be
3376 unnoticed by \PDFTEX's positioning mechanism. As a consequence, links
3377 and other annotations (that are formed in \PDF\ on a different layer
3378 then the page content) are not affected by such user-defined
3379 transformations. \PDFTEX\ 1.40.0 solves this problem with three new
3380 primitives.
3381
3382 \subsection{\cs{pdfsetmatrix}}
3383 \pdftexprimitive{\Syntax{\cs{pdfsetmatrix}}}
3384
3385 Affine transformations are normally expressed with six numbers. The
3386 first four (no unit) values defining scaling, rotating and skewing, plus
3387 two extra dimensions for translation (shifting). Since translation is
3388 handled by \TeX\ itself, the \cs{pdfsetmatrix} primitive expects as an
3389 argument a string containing just the first four numbers of the
3390 transformation separated by a space and assumes the two position
3391 coordinates to be~0.
3392
3393 For example, \verb|\pdfsetmatrix{0.87 -0.5 0.5 0.87}| rotates the
3394 current space by 30 degrees, inserting
3395 \verb|0.87 -0.5 0.5 0.87 0 0 cm| into the output. \introduced{1.40.0}
3396
3397 \subsection{\cs{pdfsave}}
3398 \pdftexprimitive{\Syntax{\cs{pdfsave}}}
3399
3400 The command saves the current transformation by inserting the \type{q}
3401 operator into the content stream. \introduced{1.40.0}
3402
3403 \subsection{\cs{pdfrestore}}
3404 \pdftexprimitive{\Syntax{\cs{pdfrestore}}}
3405
3406 The command restores previously saved transformation by inserting the
3407 \type{Q} operator into the content stream. \cs{pdfsave} and
3408 \cs{pdfrestore} pairs should always be properly nested and should start
3409 and end at the same group level. \introduced{1.40.0}
3410
3411 \section{Macro programming}
3412
3413 Expansion and other programming-related commands.
3414
3415 \subsection{\cs{expanded}}
3416 \pdftexprimitive{\Syntax{\cs{expanded} \Something{tokens}
3417 \Whatever{expandable}}}
3418
3419 Expands \Something{tokens} in exactly the same way as \cs{message}. In
3420 contrast to \cs{edef}, macro parameter characters do not need to be
3421 doubled. \cs{protected} macros (q.v.) are not expanded.
3422 \introduced{1.40.20}
3423
3424 \subsection{\cs{ifincsname}}
3425 \pdftexprimitive{\Syntax{\cs{ifincsname} \Whatever{expandable}}}
3426
3427 This conditional is true if evaluated inside \cs{csname} \ldots
3428 \cs{endcsname}, and false otherwise.
3429
3430 \subsection{\cs{ifpdfprimitive}}
3431 \pdftexprimitive{\Syntax{\cs{ifpdfprimitive} \Something{control sequence}
3432 \Whatever{expandable}}}
3433
3434 This conditional checks if the following control sequence has its
3435 primitive meaning. If so, \cs{ifpdfprimitive} is true. In any other case
3436 (redefined, made \cs{undefined}, has never been primitive), it is false.
3437 \introduced{1.40.0}
3438
3439 \subsection{\cs{ignoreprimitiveerror}}
3440 \pdftexprimitive{\Syntax{\cs{ignoreprimitiveerror} \Whatever{integer}}}
3441
3442 If this primitive parameter is set to~1, the error\\
3443 \verb|! Infinite glue shrinkage found in box being split|\\
3444 is changed from an error to a warning, and thus the exit status is not
3445 changed to failure.
3446
3447 Other values of \cs{ignoreprimitiveerror} are reserved for future use.
3448
3449 Here is a simple plain \TeX\ example to provoke that error:
3450
3451 \begin{verbatim}
3452 \ignoreprimitiveerror=1 % with this, get warning
3453 \setbox0=\vbox{\hrule height 1pt \vskip 0pt minus 1fill}
3454 \setbox1=\vsplit0 to 5pt
3455 \end
3456 \end{verbatim}
3457
3458 This parameter is defined only when the \type{-etex} option is given,
3459 like the standard \ETEX\ extensions. This is the default configuration.
3460
3461 \introduced{1.40.27}
3462
3463 \subsection{\cs{partokencontext}}
3464 \pdftexprimitive{\Syntax{\cs{partokencontext} \Something{number}}}
3465
3466 Let's call \varname{par-token} the token with the name given by
3467 \cs{partokenname}, which is \cs{par} by default (see \cs{partokenname},
3468 next). The \varname{par-token} is inserted into the input stream in
3469 different places, according to the \cs{partokencontext} value. This
3470 value can be:
3471
3472 0 (the default): {\em par-token} is inserted at empty lines (more
3473 exactly, when a token category~5 is seen in state~$N$, reading a
3474 line); before \cs{end}, \cs{vskip}, \cs{hrule}, \cs{unvbox}, and
3475 \cs{halign}, if \TeX{} is in horizontal mode when those commands are
3476 seen; and in various error recovery situations. These are the
3477 standard cases in \TeX.
3478
3479 1: {\em par-token} is inserted as above, and also at the end of
3480 \cs{vbox}, \cs{vtop}, and \cs{vcenter}, if \TeX{} is in
3481 horizontal mode at the time.
3482
3483 2: {\em par-token} is inserted as above, and also at the end of
3484 \cs{insert}, \cs{vadjust}, \cs{output}, \cs{noalign}, and
3485 items of \cs{valign}, again if \TeX{} is in horizontal mode at the
3486 time.
3487
3488 With the default \cs{partokencontext=0}, \TEX\ behaves in its normal
3489 way, namely, the situations in cases 1 and 2 are processed by a direct
3490 call of the {\em end-paragraph} routine, with no emitted {\em
3491 par-token} and no way for macros to gain control.
3492
3493 If \cs{partokencontext=1} then \TeX\ inserts the {\em par-token} in
3494 additional cases: when vertical boxes are completed but horizontal mode
3495 is not finished. Since vboxes are not uncommonly inserted directly by
3496 users, with horizontal mode material, this allows macros to control all
3497 such boxes being finished by a {\em par-token}. An example:
3498
3499 \begin{verbatim}
3500 \partokenname\_mypar
3501 \partokencontext=1
3502 \def\_mypar{Hi there!\endgraf}
3503 \vbox{Vbox text.}
3504 \end{verbatim}
3505
3506 This will output ``Hi there!''\ after ``Vbox text.''.
3507
3508 Finally, with \cs{partokencontext=2}, all cases where classical \TeX\
3509 uses the direct {\em end-paragraph} routine are changed to emit the {\em
3510 par-token} instead. In contrast to case~1, these commands are rarely
3511 invoked directly by users with horizontal mode material.
3512
3513 The setting of the register \cs{partokencontext} is local to the current
3514 group.
3515
3516 \introduced{1.40.24}
3517
3518 \subsection{\cs{partokenname}}
3519 \pdftexprimitive{\Syntax{\cs{partokenname} \Something{control sequence}}}
3520
3521 \TeX{} internally inserts a control sequence, named \cs{par} by
3522 default, into the input stream at empty lines, the end of vboxes, and
3523 various other places (see \cs{partokencontext}, above). Let's call this
3524 control sequence the \varname{par-token}.
3525
3526 Executing \cs{partokenname}\Something{control sequence} changes the
3527 name of the \varname{par-token} from \cs{par} to the given
3528 \Something{control sequence}. The setting performed by
3529 \cs{partokenname} is global.
3530
3531 This makes it possible to release the name \cs{par} to the ``user's name
3532 space''. That is, after using \cs{partokenname}, users can define and
3533 use \cs{par} as they wish without changing the behavior of anything
3534 internal to \TeX{}. For example:
3535
3536 \begin{verbatim}
3537 \catcode`\_=11
3538 \partokenname\_mypar % use \_mypar at user level
3539 \let\_mypar=\par % make \_mypar equivalent to built-in \par
3540 %
3541 \def\par{some random text} % redefine \par
3542 %
3543 Hello world.
3544
3545 Goodbye.
3546 \end
3547 \end{verbatim}
3548
3549 This will not output ``\verb|some random text|'' (the definition of
3550 \cs{par}), due to the \cs{partokenname} setting.
3551
3552 By default, the meaning of the \varname{par-token} is to end a paragraph
3553 (also named as \cs{endgraf} in the plain \TEX\ format). It can be
3554 changed as usual with, for example, \cs{def}. Naturally, it is the
3555 control sequence name given to \cs{partokenname} that must be
3556 redefined. Continuing the previous example (prior to the \cs{end}):
3557
3558 \begin{verbatim}
3559 \def\_mypar{Hi there!\endgraf}
3560 Paragraph one.
3561
3562 Paragraph two.\let\_mypar=\endgraf
3563 \end{verbatim}
3564
3565 This will output ``Hi there!''\ after ``Paragraph one.'', before ending
3566 the paragraph.
3567
3568 Another behavior of the \varname{par-token} built into \TEX\ is that
3569 macros not defined as \cs{long} cause the error ``runaway argument'' if
3570 the \varname{par-token} is scanned as a parameter. After
3571 \cs{setpartokenname}, it will be the new control sequence name that
3572 triggers this error, not \cs{par}. For instance (still continuing the
3573 same example):
3574
3575 \begin{verbatim}
3576 \def\amac#1{}
3577 \amac{long test, no error: \par}
3578 \amac{long test, gives error: \_mypar}
3579 \end{verbatim}
3580
3581 \introduced{1.40.24}
3582
3583 \subsection{\cs{pdfprimitive}}
3584 \pdftexprimitive{\Syntax{\cs{pdfprimitive} \Something{control sequence}}}
3585
3586 This command executes the primitive meaning of the following control
3587 sequence, regardless of whether the control sequence has been redefined
3588 or made undefined. If the primitive was expandable, \cs{pdfprimitive}
3589 expands also. On the other hand, if the following control sequence never
3590 was a primitive, nothing happens and no error is raised. (In some
3591 versions of \PDFTEX\ prior to 1.40.19, an error was wrongly given.)
3592 \introduced{1.40.0}
3593
3594 \section{Typesetting}
3595
3596 \subsection{\cs{pdfinsertht}}
3597 \pdftexprimitive{\Syntax{\cs{pdfinsertht} \Something{integer}
3598 \Whatever{expandable}}}
3599
3600 If \Something{integer} is the number of an insertion class, this command
3601 returns the current height of the corresponding box. For instance, the
3602 following returns \type{12pt} in plain \TEX:
3603
3604 \begin{verbatim}
3605 Abc\footnote*{Whatever.}\par
3606 \pdfinsertht\footins
3607 \end{verbatim}
3608
3609 \subsection{\cs{pdflastxpos}, \cs{pdflastypos}}
3610 \pdftexprimitive{\Syntax{\cs{pdflastxpos} \Whatever{read-only integer}}}
3611 \pdftexprimitive{\Syntax{\cs{pdflastypos} \Whatever{read-only integer}}}
3612
3613 This primitive returns an integer number representing the absolute $x$
3614 resp.\ $y$ coordinate of the last point marked by \cs{pdfsavepos}. The
3615 unit is scaled points (sp).
3616
3617 \subsection{\cs{pdfsavepos}}
3618 \pdftexprimitive{\Syntax{\cs{pdfsavepos} \Modelist{h, v, m}}}
3619
3620 This primitive marks the current absolute ($x,y$) position on the media,
3621 with the reference point in the lower left corner. It is active only
3622 during page shipout, when the final page is assembled. The position
3623 coordinates can then be retrieved by the \cs{pdflastxpos} and
3624 \cs{pdflastypos} primitives, and \eg\ written out to some auxiliary
3625 file. The coordinates can be used only after the current \cs{shipout}
3626 has been finalized, therefore normally two \PDFTEX\ runs are required to
3627 utilize these primitives. Starting with \PDFTEX\ 1.40.0, this mechanism
3628 can also be used while running in \DVI\ mode.
3629
3630 \subsection{\cs{quitvmode}}
3631 \pdftexprimitive{\Syntax{\cs{quitvmode}}}
3632
3633 The primitive instructs \PDFTEX\ to quit vertical mode and start
3634 typesetting a paragraph. Thus, \cs{quitvmode} has the same basic effect
3635 as the \cs{leavevmode} macro from \type{plain.tex}. However,
3636 \cs{leavevmode} expands the \cs{everypar} token list, which may or may
3637 not be desired. \cs{quitvmode} does not expand \cs{everypar}.
3638 \introduced{1.21a}
3639
3640 \subsection{\cs{vadjust}}
3641 \pdftexprimitive{\Syntax{\cs{vadjust}
3642 \Optional{\Something{pre spec}}
3643 \Something{filler}
3644 \Lbrace \Something{vertical mode material} \Rbrace
3645 \Modelist{h, m}
3646 }}
3647
3648 In \PDFTEX, the \cs{vadjust} primitive supports an additional optional
3649 qualifier \Something{pre spec}, which is simply the string \type{pre},
3650 to the original \TEX. If no \type{pre} is given, \cs{vadjust} behaves
3651 exactly as the original (see {\em The \TEX book}, p.~281): it appends an
3652 adjustment item created from \Something{vertical mode material} to the
3653 current list {\em after} the line in which \cs{vadjust} appears. In
3654 contrast, with the qualifier \type{pre}, the adjustment item is put {\em
3655 before} the line in which \cs{vadjust pre} appears.
3656
3657 \section{Tracing}
3658
3659 \subsection{\cs{showstream}}
3660 \pdftexprimitive{\Syntax{\cs{showstream} \Whatever{integer}}}
3661
3662 If this primitive parameter has a value corresponding to an open output
3663 stream (which has been opened with \cs{openout}), then any \cs{show},
3664 \cs{showthe}, \cs{showbox} or \cs{showlists} commands do not write
3665 output to the terminal, but instead write only to the referenced output
3666 stream, as if they were written with \cs{immediate}\cs{write}.
3667
3668 For example:
3669 \begin{verbatim}
3670 \newwrite\myoutstream
3671 \immediate\openout\myoutstream="infofile"
3672 \showstream=\myoutstream
3673 % From now on, \show... commands are redirected to "infofile.tex".
3674 \show\TeX
3675 %
3676 \showstream=-1
3677 % -1 is never a open file and therefore restores
3678 % normal \show... behavior.
3679 \immediate\closeout\myoutstream
3680 \end{verbatim}
3681
3682 This example would not generate any special output to the terminal or
3683 log file (except for any logging done by \cs{newwrite}. It writes
3684 this text to \type{infofile.tex}, including the initial blank line,
3685 since that is what \cs{show} does:
3686
3687 \begin{verbatim}
3688
3689 > \TeX=macro:
3690 ->T\kern -.1667em\lower .5ex\hbox {E}\kern -.125emX
3691 \end{verbatim}
3692
3693 This primitive is available, with identical behavior, in all \TeX\
3694 engines except the original \TEX\ and \eTeX, where \cs{showstream}
3695 remains undefined. \introduced{1.40.24}
3696
3697 \subsection{\cs{tracinglostchars}}
3698 \pdftexprimitive{\Syntax{\cs{tracinglostchars} \Whatever{integer}}}
3699
3700 This primitive parameter has always been part of \TEX, and its operation
3701 with values $\le2$ is unchanged. In addition, if its value is
3702 $\ge3$, then ``Missing character'' reports become full errors
3703 (ordinarily they are only logged), and the character code is reported in
3704 hex. For example:
3705
3706 \begin{verbatim}
3707 \tracinglostchars=3
3708 \font\x=logo10 \x \char99 \end
3709 \end{verbatim}
3710
3711 \noindent will result in this error message:
3712
3713 \begin{verbatim}
3714 ! Missing character: There is no c ("63) in font logo10.
3715 \end{verbatim}
3716
3717 \noindent (The \type{logo10} font only defines the capital letters used
3718 in the \METAFONT\ and \METAPOST\ logos, so there is no lowercase.)
3719
3720 This new behavior is essentially the same in all \TeX\ engines except
3721 the original \TEX\ and \eTeX, where the behavior of
3722 \cs{tracinglostchars} remains unchanged.
3723
3724 \introduced{1.40.22}
3725
3726 \subsection{\cs{tracingstacklevels}}
3727 \pdftexprimitive{\Syntax{\cs{tracingstacklevels} \Whatever{integer}}}
3728
3729 If this primitive parameter is $>0$, and $\cs{tracingmacros}>0$, macro
3730 expansion logging is truncated at the specified depth. Also, and more
3731 importantly, each relevant log line is given a prefix beginning with
3732 \type{~}, either followed by a \type{.} character for each expansion
3733 level or another \type{~} if the expansion was truncated. For example:
3734
3735 \begin{verbatim}
3736 \tracingmacros=1 % so macro expansion is logged at all
3737 \tracingstacklevels=2 % cut off at level 2
3738 \def\a#1{\relax} % argument to show parameter logging is affected too
3739 \def\b#1{\a{#1}}
3740 \b1
3741 \end{verbatim}
3742
3743 \noindent logs the following:
3744
3745 \begin{verbatim}
3746 ~.\b #1->\a {#1}
3747 #1<-1
3748 ~~\a
3749 \end{verbatim}
3750
3751 Thus, the expansion of \cs{b} is logged normally, with the addition
3752 of the \type{~.} prefix. The expansion of \cs{a} is truncated
3753 (level~2), hence neither the parameters nor body expansion are shown.
3754
3755 Furthermore, an \cs{input} file counts as an expansion level, and the
3756 input filename is logged. So, if we add this to our example above:
3757 \begin{verbatim}
3758 \input anotherfile
3759 \end{verbatim}
3760
3761 \noindent where \type{anotherfile.tex} simply contains \cs{b2}, the log
3762 will get:
3763
3764 \begin{verbatim}
3765 ~.INPUT anotherfile.tex
3766 ~~\b
3767 ~~\a
3768 \end{verbatim}
3769
3770 Now the \cs{b} expansion is not logged either, since the expansion
3771 depth is higher than the \cs{tracingstacklevels} value.
3772
3773 The intended use of \cs{tracingstacklevels} is not so much to truncate
3774 logging as to indicate expansion levels for detailed debugging. Thus
3775 normally it would be set to a large number (\cs{maxdimen}), so that
3776 everything is fully logged, with the addition of the expansion level
3777 indication with the number of dots in the prefix.
3778
3779 This primitive is available, with identical behavior, in all \TeX\
3780 engines except the original \TEX\ and \eTeX, where
3781 \cs{tracingstacklevels} remains undefined. \introduced{1.40.22}
3782
3783 \section{\PDFTEX\ execution environment}
3784
3785 \subsection{\cs{pdfdraftmode}}
3786 \pdftexprimitive{\Syntax{\cs{pdfdraftmode} \Whatever{integer}}}
3787
3788 When set to 1 (or set by the command-line switch \type{-draftmode}),
3789 \PDFTEX\ doesn't write the output \PDF\ file and doesn't read any
3790 images, but does do everything else (including writing auxiliary files),
3791 thus speeding up compilations when you know you need an extra run but
3792 don't care about the output, \eg\ just to get cross-references started.
3793 If specified, the parameter must appear before any data is written to
3794 the \PDF\ output. \introduced{1.40.0}
3795
3796 \subsection{\cs{pdfshellescape}}
3797 \pdftexprimitive{\Syntax{\cs{pdfshellescape} \Whatever{read-only integer}}}
3798
3799 This primitive is~1 if \cs{write18} is enabled, 2 if its operation is
3800 restricted to known-safe programs, and 0 otherwise. \introduced{1.30.0}
3801
3802 \subsection{\cs{pdftexbanner}}
3803 \pdftexprimitive{\Syntax{\cs{pdftexbanner} \Whatever{expandable}}}
3804
3805 Returns the \PDFTEX\ banner message, \eg\ for the version used here:
3806 {\tt \pdftexbanner}. \introduced{1.20a}
3807
3808 \subsection{\cs{pdftexrevision}}
3809 \pdftexprimitive{\Syntax{\cs{pdftexrevision} \Whatever{expandable}}}
3810
3811 Returns the revision number of \PDFTEX, \eg\ for \PDFTEX\ version
3812 \currentpdftex\ (used to produce this document), it returns the number
3813 {\tt \pdftexrevision}.
3814
3815 \subsection{\cs{pdftexversion}}
3816 \pdftexprimitive{\Syntax{\cs{pdftexversion} \Whatever{read-only integer}}}
3817
3818 Returns the version of \PDFTEX\ multiplied by 100, excluding the tertiary
3819 version number, \eg\ for \PDFTEX\ version \currentpdftex\ (used to
3820 produce this document), it returns {\tt \number\pdftexversion}.
3821
3822 \chapter{Graphics}
3823 \label{chap.graphics}
3824
3825 \PDFTEX\ natively supports inclusion of pictures in \PNG, \JPEG,
3826 \JBIGTWO, and \PDF\ format; a few differences between these are
3827 discussed below. Other formats, notably \METAPOST, are supported through
3828 \TEX\ macros.
3829
3830 The historically common technique for including graphics with \TEX,
3831 using \EPS\ figures, is not (and cannot be) supported; \PDF\ inclusion
3832 is usually the easiest replacement, as described next.
3833
3834 \section{\PDF\ graphics}
3835
3836 \PDFTEX\ allows inserting selected pages from \PDF\ files, carrying
3837 their own fonts, graphics, and pixel images, into a document. The first
3838 figure in this manual (figure~\ref{fig.titleout}) is an example of such
3839 an insert, being a one-page \PDF\ document (uncompressed) generated by
3840 \PDFTEX.
3841
3842 By default \PDFTEX\ takes the BoundingBox of a \PDF\ file from its
3843 CropBox if available, otherwise from its MediaBox. This can be
3844 influenced by the \Something{pdf box spec} option to the \cs{pdfximage}
3845 primitive, or by setting the \cs{pdfpagebox} or \cs{pdfforcepagebox}
3846 primitives to a value corresponding to the desired box type.
3847
3848 To get the right BoundingBox from a \EPS\ file, before converting to
3849 \PDF, it is necessary to transform the \EPS\ file so that the start
3850 point is at the (0,0)~coordinate and the page size is set exactly
3851 corresponding to the BoundingBox. A \PERL\ script (\EPSTOPDF,
3852 \url{https://ctan.org/pkg/epstopdf}) is available for this purpose; it
3853 can remove some garbage from input files, among other conveniences. The
3854 \PSTOPDF\ program that comes with \GHOSTSCRIPT\ can do a similar job.
3855
3856 \section{\PNG\ graphics}
3857
3858 The lossless compressing \PNG\ format is useful for embedding crisp
3859 pixel graphics (\eg\ line scans, screenshots). As of \PDFTEX\ 1.30.0,
3860 the alpha channel of \PNG\ images is processed if available; this allows
3861 embedding of images with simple transparency. The \PNG\ format does not
3862 support the CMYK color model, which is sometimes required for print
3863 media (this often can be replaced by four component \JPEG\ in high
3864 quality or lossless compression mode). Photos in \PNG\ format have
3865 rather poor compression; for that, \JPEG\ format is preferable.
3866
3867 Embedding \PNG\ images in the general case requires \PDFTEX\ to
3868 uncompress the pixel array and then re\hyph compress it to the \PDF\
3869 format's requirements; this can take a noticeable amount of time. Since
3870 \PDFTEX\ 1.30.0 there is also a fast \PNG\ embedding mode that does not
3871 need uncompressing: the image data are directly copied into the \PDF\
3872 stream, resulting in a much higher embedding speed. This direct-copy
3873 mode can only be used if the image array structure of the \PNG\ file is
3874 compatible with the \PDF\ image structure; \eg\ an interlaced \PNG\
3875 image requires uncompressing to rearrange the image lines. The use of
3876 gamma correction also disables fast copying, as it requires calculations
3877 with individual pixels.
3878
3879 Whether the fast copy mode is used for a \PNG\ image can be seen from
3880 the log file, which then shows the string `(PNG copy)' after the \PNG\
3881 file name. Further, as of \PDFTEX\ 1.40.29 (2026), if the environment
3882 variable \type{TEXMF_DEBUG_PNG_COPY} is set to 1, \PDFTEX\ reports
3883 various attributes of each \PNG\ image as well as whether it was copied.
3884 Thus it's possible to discern why a given image was not copied, and
3885 perhaps do mass conversions beforehand to speed up the \PDFTEX\ run. See
3886 the mailing list thread around
3887 \url{https://tug.org/pipermail/tex-live/2026-February/052105.html} for
3888 some conversion incantations and other PNG image attributes which
3889 prevent copying (some keywords: RGBA, cHRM, bKGD, colortype~3 palettes).
3890
3891 \section{\JPEG\ graphics}
3892
3893 The \JPEG\ format is normally used in lossy mode; then it's ideal for
3894 embedding photos. It's not recommended for crisp images from synthetic
3895 sources with a limited amount of colors. Both \JFIF\ and \EXIF\ are
3896 supported for additional information.
3897
3898 \section{\JBIGTWO\ graphics}
3899
3900 The \JBIGTWO\ format works only for bi-tonal (black and white) pixel
3901 images like scanned line and text documents, but for these it has
3902 typically a much higher compression ratio than the other two pixel image
3903 formats. The \JBIGTWO\ format is part of the \PDF\ standard since
3904 version 1.5; native \JBIGTWO\ image inclusion is available in \PDFTEX\
3905 since version 1.40.0.
3906
3907 A \JBIGTWO\ file might contain many images, which gives an even better
3908 compression ratio than with a single image per file, as \JBIGTWO\
3909 encoders can exploit similarities between bit patterns over several
3910 images. Encoders for \JBIGTWO\ can operate in lossy as well as lossless
3911 modes.
3912
3913 A free \JBIGTWO\ encoder is available, \useurl{jbigenc}; perhaps there
3914 are others.
3915
3916 \section{\METAPOST\ graphics}
3917
3918 Although the output of \METAPOST\ is \POSTSCRIPT, it is in a highly
3919 simplified form. Thus, \TEX\ macros, available as \type{supp-pdf.tex}
3920 and \type{supp-pdf.mkii}, have been written to read \METAPOST\ output
3921 and support all of its features. Thus, \METAPOST\ output files can be
3922 read directly in \TEX. A \METAPOST\ to \PDF\ conversion script,
3923 \MPTOPDF\ (\url{https://ctan.org/pkg/mptopdf}), is also available. All
3924 this support is due to Hans Hagen and Tanmoy Bhattacharya.
3925
3926 \section{\TEX\ package graphics: picture mode, Xy-pic, tpic}
3927
3928 Other options for graphics in \PDFTEX:
3929
3930 \begin{description}
3931 \item[\LATEX\ picture mode] Since this is implemented in terms
3932 of font characters, it works in exactly the same way as usual.
3933
3934 \item[Xy-pic] If the \POSTSCRIPT\ backend is not requested, Xy-pic
3935 uses its own Type~1 fonts, and needs no special attention.
3936
3937 \item[tpic] The tpic \cs{special} commands (used in some
3938 macro packages) can be redefined to produce literal \PDF, using some
3939 macros written by Hans Hagen.
3940
3941 \end{description}
3942
3943 \section{\POSTSCRIPT\ graphics: Not supported, but convertable}
3944
3945 The inclusion of raw \POSTSCRIPT\ commands, a technique utilized by, for
3946 instance, the \type{pstricks} package, cannot be supported directly.
3947 Although \PDF\ is a direct descendant of \POSTSCRIPT, it lacks any
3948 programming language commands, and cannot deal with arbitrary
3949 \POSTSCRIPT.
3950
3951 Although \POSTSCRIPT\ graphics are not supported, when \PDFLATEX\ tries
3952 to read an \type{.eps} file, by default it automatically converts it to
3953 \type{.pdf}, using \EPSTOPDF. This is done by \LATEX-specific macros,
3954 not the \PDFTEX engine.
3955
3956 \chapter{Additional \PDF\ keys: \texttt{PTEX.*}}
3957 \label{sec.addpdfkeys}
3958
3959 {\em This section is based on the manual on keys written by Martin Schr\"oder.}
3960
3961 A \PDF\ document should contain only the structures and attributes defined
3962 in the \PDF\ specification. However, the specification allows applications
3963 to insert additional keys, provided they follow certain rules.
3964
3965 The most important rule is that developers have to register with Adobe
3966 prefixes for the keys they want to insert. Hans Hagen has registered the
3967 prefix \type{PTEX} for \PDFTEX.
3968
3969 \PDFTEX\ generates an XObject for every included \PDF\ image. The dictionary of
3970 this object contains these additional keys:
3971
3972 \begin{smalltable}
3973 \begin{tabular}{lll}
3974 \bf key & \bf type & meaning \cr
3975 \tt PTEX.FileName & string & The name of the included file as seen by
3976 \PDFTEX. \cr
3977 \tt PTEX.InfoDict & dictionary & The \type{InfoDict}
3978 of the included \PDF\ (an indirect
3979 object). \cr
3980 \tt PTEX.PageNumber & integer & The page number of the included file. \cr
3981 \end{tabular}
3982 \end{smalltable}
3983
3984 The \PDFReference\ says: ``Although viewer applications can
3985 store custom metadata in the document information dictionary, it is
3986 inappropriate to store private content or structural information there;
3987 such information should be stored in the document catalog instead.''
3988
3989 Although it would seem more natural to put this information in the
3990 document information dictionary, we have to obey the rules laid down in
3991 the \PDFReference. The following key ends up in the document catalog.
3992
3993 \begin{smalltable}
3994 \begin{tabular}{llp{.66\hsize}}
3995 \bf key & \bf type & meaning \cr
3996 \tt PTEX.Fullbanner & string & The full version of the \PDFTEX\
3997 binary that produced the file as displayed by {\tt pdftex
3998 \type{--version}}, a.k.a.\ \cs{pdftexbanner} ({\tt\pdftexbanner}).
3999 This is necessary because the string in the \type{Producer} key in
4000 the info dictionary is rather short, namely {\tt
4001 pdfTeX-\currentpdftex}. \cr
4002 \end{tabular}
4003 \end{smalltable}
4004
4005 Any or all of these keys can be suppressed with the
4006 \cs{pdfsuppressptexinfo} primitive, described in
4007 section~\ref{sec.docinfocatalog}.
4008
4009 \chapter{Character translation: \TCX}
4010
4011 Characters that are input to \PDFTEX\ are subject to optional \TEX\
4012 character translation (\TCX) under control of a \TCX\ file. The \TCX\
4013 maps the input character codes (\eg\ from \cs{input} or \cs{read}) to
4014 the character codes as seen by \PDFTEX. This mapping takes place before
4015 the characters enter \PDFTEX's `mouth'. If no \TCX\ file is read, the
4016 input characters enter \PDFTEX\ directly; no mapping is done.
4017
4018 \TCX\ files consist of lines each containing one or two integer numbers
4019 in the range 0..255, either in decimal or hex notation. A comment sign
4020 \type{%} in a \TCX\ line starts a comment until the end of line. The
4021 first number in each line is for matching the input character code, the
4022 second, optional number is the corresponding \TEX\ character code. If a
4023 line contains only one number, characters with this code enter \PDFTEX\
4024 unchanged; no mapping is done.
4025
4026 \TCX\ mapping also influences \PDFTEX\ output streams for \cs{message}
4027 and \cs{write}. Without \TCX\ mapping, only characters that are within
4028 the range 32..126 are flagged as `printable', meaning that these
4029 characters are output directly by \cs{message} and \cs{write}
4030 primitives. Characters outside the range 32..126 are instead output in
4031 escaped form, \eg\ as \type{^^A} for a character with code \type{0x01}.
4032 When a character code is mentioned in the 2nd column of the \TCX\ file,
4033 or as the only value in a line, it is flagged as `printable'. During
4034 \cs{message} and \cs{write}, output characters are mapped in reverse
4035 direction: they are looked up in the 2nd column of the \TCX\ file and
4036 the corresponding values from the 1st column are output. Again, if a
4037 \PDFTEX\ character code is found as the only number in a line, no
4038 mapping is done. Mentioning a character code as the only number on a
4039 line has the sole purpose to flag this code `printable'.
4040
4041 The characters output into the \PDF\ file, \eg\ by the \cs{pdfliteral}
4042 or \cs{special} primitives, are not subject to \TCX\ output remapping.
4043
4044 Beware: Character translation interferes with the \ENCTEX\ primitives; to
4045 avoid surprises, don't use \ENCTEX\ and \TCX\ mapping at the same time.
4046 Further details about \TCX\ file loading can be found in the \WEBC\
4047 manual, \useurl{tcxfiles}.
4048
4049 Nowadays \TCX\ files are rarely used. The \type{-8bit} command line
4050 option makes all characters printable, when that is desired.
4051
4052 \appendix
4053
4054 \chapter{Installation}
4055
4056 This section describes the steps needed to get \PDFTEX\ running on a
4057 system where \PDFTEX\ is not yet installed. Nowadays all known \TEX\
4058 distributions, such as \TEXLIVE, \MIKTEX, and \MACTEX, include \PDFTEX\
4059 already. For example, the \TEXLIVE\ distribution comes with \PDFTEX\
4060 versions for many \UNIX, \WIN, and Mac systems; more information
4061 can be found at \hbox{\useurl{texlive}.} When you use any of these
4062 distributions, you don't need to bother with the \PDFTEX\ installation
4063 procedure in this chapter.
4064
4065 If there is no precompiled \PDFTEX\ binary for your system, or the
4066 version coming with a distribution is not the current one and you would
4067 like to try out a fresh \PDFTEX\ immediately, you will need to build
4068 \PDFTEX\ from sources; read on. You should already have a working \TEX\
4069 system, \eg\ \TEXLIVE, into which the freshly compiled \PDFTEX\ will be
4070 integrated. (Numerous support files are required in order to have a
4071 working binary.) Note that the installation description in this manual
4072 is \WEBC\hyph specific.
4073
4074 \section{Getting sources and binaries}
4075
4076 The primary home page is \useurl{ptexorg}, where you also find bug
4077 tracking information. Development sources are at \useurl{ptexdevel}.
4078 Precompiled binaries for some platforms are available in subdirectories
4079 below \useurl{ctansystems}, although these are unlikely to be up to
4080 date. Your best bet is to use a current \TEX\ distribution.
4081
4082 \section{Compiling}
4083
4084 Given a directory where the sources have been downloaded or checked out,
4085 some working on a \UNIX\ system the following steps are needed to
4086 compile \PDFTEX:
4087
4088 \begin{verbatim}
4089 cd source # from branches/stable!
4090 ./build-pdftex.sh
4091 \end{verbatim}
4092
4093 The binary \filename{pdftex} will hopefully then end up in the
4094 subdirectory \filename{build-pdftex/texk/web2c}. The additional
4095 utilities \filename{pdftosrc} and \filename{ttf2afm} are in the \PDFTEX\
4096 source repository, but are not built by default. If they are needed,
4097 edit \filename{build-pdftex.sh} to \type{--enable} them.
4098
4099 For \PDFTEX\ maintainers: a sibling script to \type{build-pdftex.sh} is
4100 in the repository, namely \type{sync-pdftex.sh}, which syncs changes
4101 from a \TEXLIVE\ source repository to a \PDFTEX\ source repository. Read
4102 and understand the script before using it!
4103
4104 \section{Placing files}
4105
4106 The next step is to put the newly-compiled \filename{pdftex} (and, if
4107 enabled, \filename{pdftosrc} and/or \filename{ttf2afm}) binaries into
4108 the installed distribution. \Eg\ for a typical \TEXLIVE\ system:\\
4109 \texttt{/usr/local/texlive/\rcsyear/bin/}\type{x86_64-linux}, replacing
4110 \type{x86_64-linux} with the appropriate platform name. (As always, it
4111 is sensible to rename the installed \filename{pdftex} binary first and
4112 not just overwrite it.)
4113
4114 If you're doing this into a live hierarchy, run \verb|fmtutil-sys refresh|
4115 afterwards, so that all formats are regenerated system-wide
4116 with the new \filename{pdftex} binary.
4117
4118 If what you want is to test a new version of \filename{pdftex}, and not
4119 replace the installed version, the best approach is to copy it into the
4120 binary directory as, say, \filename{pdftex.new}. The different
4121 executable name can sometimes change the files found and other behavior,
4122 but usually this won't matter.
4123
4124 \PDFTEX\ uses the Kpathsea library to search for supporting files; many
4125 variables and configuration files can come into play. See the Kpathsea
4126 manual: \useurl{kpathsea}.
4127
4128 \section{Configuration of \PDFTEX}
4129 \label{sec.cfg}
4130
4131 As opposed to \TEX\ with its \DVI\ output, the \PDFTEX\ program does not
4132 have a separate postprocessing stage to transform the \TEX\ input into
4133 final \PDF. As a consequence, all data needed for building the \PDF\
4134 must be available during the \PDFTEX\ run, in particular information on
4135 media dimensions and offsets, graphics files for embedding, and font
4136 information (font files, encodings).
4137
4138 When \TEX\ builds a page, it places items relative to the (1in,1in)
4139 offset from the top left page corner (the \DVI\ reference point).
4140 Separate \DVI\ postprocessors allow specifying the paper size (\eg\ A4
4141 or letter), so that this reference point is moved to the correct
4142 position on the paper, and the text ends up at the right place.
4143
4144 In \PDF, the paper dimensions are part of the page definition, and
4145 \PDFTEX\ therefore requires that they be defined at the beginning of the
4146 \PDFTEX\ run. As with pages described by \POSTSCRIPT, the \PDF\
4147 reference point is in the lower left corner.
4148
4149 Formerly, these dimensions and other \PDFTEX\ parameters were read in
4150 from a configuration file named \filename{pdftex.cfg}, which had a
4151 special (non-\TEX) format, at the start of processing. Nowadays such a
4152 file is ignored by \PDFTEX. Instead, the page dimensions and offsets, as
4153 well as many other parameters, can be set by \PDFTEX\ primitives during
4154 the \PDFTEX\ format building process, so that the settings are dumped
4155 into the fresh format and consequently will be used when \PDFTEX\ is
4156 later called with that format. All settings from the format can still be
4157 overridden during a \PDFTEX\ run by using the same primitives. This
4158 configuration concept is a more unified approach, as it avoids a
4159 configuration file with a special format.
4160
4161 A list of \PDFTEX\ primitives likely relevant to setting up the \PDFTEX\
4162 engine is given in the table below. All primitives are described in
4163 detail in previous sections.
4164
4165 \begin{smalltable}
4166 \begin{tabular}{@{}llll@{}}
4167 \bf primitive name & \bf type & \bf default & \bf comment\cr
4168 \cs{pdfoutput} & integer & 0 & \DVI\ by default \cr
4169 \cs{pdfadjustspacing} & integer & 0 & off \cr
4170 \cs{pdfcompresslevel} & integer & 9 & best \cr
4171 \cs{pdfobjcompresslevel} & integer & 0 & no object streams \cr
4172 \cs{pdfdecimaldigits} & integer & 3 & \cr
4173 \cs{pdfimageresolution} & integer & 72 & dpi \cr
4174 \cs{pdfpkresolution} & integer & 0 & \cr
4175 \cs{pdfpkmode} & tokens & empty & mode per \type{mktex.cnf}\cr
4176 \cs{pdfuniqueresname} & integer & 0 & \cr
4177 \cs{pdfprotrudechars} & integer & 0 & \cr
4178 \cs{pdfgentounicode} & integer & 0 & \cr
4179 \cs{pdfmajorversion} & integer & 1 & output \PDF\ 1.x \cr
4180 \cs{pdfminorversion} & integer & 4 & specifically \PDF\ 1.4 \cr
4181 \cs{pdfpagebox} & integer & 0 & \cr
4182 \cs{pdfforcepagebox} & integer & 0 & \cr
4183 \cs{pdfinclusionerrorlevel} & integer & 0 & \cr
4184 %----------------------------------------------------------------------------
4185 \cs{pdfhorigin} & dimension & 1in & \cr
4186 \cs{pdfvorigin} & dimension & 1in & \cr
4187 \cs{pdfpagewidth} & dimension & 0pt & \cr
4188 \cs{pdfpageheight} & dimension & 0pt & \cr
4189 \cs{pdflinkmargin} & dimension & 0pt & \cr
4190 \cs{pdfdestmargin} & dimension & 0pt & \cr
4191 \cs{pdfthreadmargin} & dimension & 0pt & \cr
4192 \cs{pdfmapfile} & text & \filename{pdftex.map} & not dumped\cr
4193 \end{tabular}
4194 \end{smalltable}
4195
4196 Figure~\ref{fig.configfile} shows a recent \PDFTEX\ configuration file
4197 (\type{pdftexconfig.tex}) from \TEXLIVE\ (part of the
4198 \type{tex-ini-files} package), overriding some of these settings. It is
4199 read when a format is built. It enables \PDF\ output, sets paper
4200 dimensions and the default pixel density for \PK\ font inclusion. The
4201 default values are chosen so that \PDFTEX\ often can be used (\eg\ in
4202 \type{-ini} mode) without setting any additional parameters.
4203
4204 \begin{figure}[t]
4205 \myverbatiminput{incl/pdftexconfig.txt}
4206 \caption{\PDFTEX\ configuration file for \TEXLIVE\
4207 (\texttt{pdftexconfig.tex}).}
4208 \label{fig.configfile}
4209 \end{figure}
4210
4211 Independent of whether such a configuration file is read, the first
4212 action in a \PDFTEX\ run is reading the global \WEBC\ configuration file
4213 (\filename{texmf.cnf}), which is common to all programs in the \WEBC\
4214 system. This file mainly defines file search paths, the memory layout
4215 (\eg\ string pool and hash size), and a few other general parameters.
4216
4217 \section{Creating format files}
4218
4219 The \PDFTEX\ engine supports building separate formats for either \DVI\
4220 or \PDF\ output in the same way as the classical \TEX\ engine does for
4221 \DVI. Format generation (and other \type{initex} features) is enabled by
4222 the \type{-ini} option. The default mode (\DVI\ or \PDF) can be chosen
4223 either on the command line by setting the option \type{-output-format}
4224 to \type{dvi} or \type{pdf}, or by setting the \cs{pdfoutput} parameter.
4225 The format file inherits this setting, so that a later invocation of
4226 \PDFTEX\ with this format starts in the preselected mode (which can
4227 still be overridden). A format file can be read in only by the engine
4228 that has generated it; a format incompatible with an engine leads to a
4229 fatal error.
4230
4231 It is customary to package the configuration and macro file input into a
4232 \type{.ini} file. \Eg\ the file \type{etex.ini} in
4233 figure~\ref{fig.etex.ini} is for generating an \ETEX\ format with \DVI\
4234 output. It has been traditional for many years to generate
4235 \type{etex.fmt} with \PDFTEX\ rather than the original \ETEX, because
4236 \PDFTEX\ contains useful additional programming and other
4237 non-\PDF-related features.
4238
4239 The \type{pdfetex.ini} file figure~\ref{fig.pdfetex.ini} shows the
4240 corresponding format with \PDF\ output by default; this is what creates
4241 the format file read when \type{pdftex} is normally invoked.
4242
4243 The corresponding \PDFTEX\ invocations for format generation are:
4244
4245 \begin{verbatim}
4246 pdftex -ini *etex.ini
4247 pdftex -ini *pdfetex.ini
4248 \end{verbatim}
4249
4250 These calls produce format files \filename{etex.fmt},
4251 \filename{pdfetex.fmt}, as the default format file name is taken from
4252 the input file name. You can override this with the \type{-jobname}
4253 option. The asterisk \type{*} before the file name is an unusual flag,
4254 only used in \type{-ini} mode, which causes the \PDFTEX\ engine to
4255 enable \ETEX's features.
4256
4257 To reiterate, the distribution (\TEXLIVE, \MIKTEX) usually takes care of
4258 format (re)generation. The above is if you need to do such things
4259 manually for testing, debugging, development, etc.
4260
4261 Incidentally, as of \PDFTEX\ 1.40.21 (\TEX\ Live 2020), \filename{.fmt}
4262 files are compressed with \type{zlib}. This makes for a considerable
4263 savings in space, and consequently in time.
4264
4265 \begin{figure}[t]
4266 \myverbatiminput{incl/ini-etex.txt}
4267 \caption{The \type{etex.ini} file to dump the plain \ETEX\ format with
4268 \DVI\ output.}
4269 \label{fig.etex.ini}
4270 \end{figure}
4271
4272 \begin{figure}[t]
4273 \myverbatiminput{incl/ini-pdfetex.txt}
4274 \caption{The \type{pdfetex.ini} file to dump plain \ETEX\ with \PDF\ output.}
4275 \label{fig.pdfetex.ini}
4276 \end{figure}
4277
4278 \section{Testing the installation}
4279
4280 When everything is set up, you can test the installation. A simple test
4281 of plain \PDFTEX\ is:
4282
4283 \begin{verbatim}
4284 pdftex story \\end
4285 \end{verbatim}
4286
4287 This should typeset the famous one-page short story by A.U. Thor,
4288 generating a \PDF\ file.
4289
4290 A more thorough and descriptive test is the plain \TEX\ test file
4291 \filename{samplepdf.tex}, available in the distribution in the
4292 \type{samplepdftex/} directory. Process this file by typing:
4293
4294 \begin{verbatim}
4295 pdftex samplepdf
4296 \end{verbatim}
4297
4298 If the installation is ok, this should produce a file called
4299 \filename{samplepdf.pdf}. The file \filename {samplepdf.tex} is also a
4300 good place to look for examples of how to use \PDFTEX's primitives.
4301
4302 \section{Common problems}
4303
4304 The most common problem with installations is that \PDFTEX\ complains
4305 that some file cannot be found. In such cases, first make sure that all
4306 \TEX-related environment variables are unset. For detailed debugging,
4307 set the environment variable \type{KPATHSEA_DEBUG=255} before running
4308 \PDFTEX\ or use the option \verb|-kpathsea-debug 255|. More options can
4309 be found in the \WEBC\ documentation.
4310
4311 Variables in \filename{texmf.cnf} can be overwritten by environment
4312 variables. Here are some of the most common problems you can encounter
4313 when getting started:
4314
4315 \begin{itemize}
4316 \item \verb|I can't find the format file `pdftex.fmt'!| \newline
4317 \verb|I can't find the format file `pdflatex.fmt'!|
4318
4319 The format file is not created (see above how to do that) or
4320 is not properly placed. Make sure that \type{TEXFORMATS} in
4321 \filename {texmf.cnf} contains the path to \filename {pdftex.fmt}
4322 or \filename {pdflatex.fmt}.
4323
4324 \item \verb|Fatal format file error; I'm stymied|
4325
4326 This typically appears if you forgot to regenerate the \type{.fmt}
4327 files after installing a new version of the \PDFTEX\ binary.
4328 The first line tells by which engine the offending format was generated.
4329
4330 \item \PDFTEX\ cannot find one or more map files (\type{*.map}),
4331 encoding vectors (\type{*.enc}), virtual fonts, Type~1 fonts,
4332 TrueType or OpenType fonts, or some image file.
4333
4334 Make sure that the required file exists and the corresponding variable
4335 in \filename{texmf.cnf} contains a path to the file.
4336
4337 When you have installed new fonts, and your \PDF\ viewer complains
4338 about missing fonts, you should take a look at the log file produced
4339 by \PDFTEX. Missing fonts, map files, encoding vectors as well as
4340 missing characters (glyphs) are reported there.
4341 \end{itemize}
4342
4343 For more help resources of all kinds, see \useurl{tughelp}.
4344
4345 \chapter{Formal syntax specification}
4346 \label{sec.syntax}
4347
4348 This appendix formally specifies the \PDFTEX-specific extensions to the
4349 \TEX\ macro programming language. Most primitive names are prefixed by
4350 `\type{pdf}'. General definitions and syntax rules follow after the list
4351 of primitives.
4352
4353 Two new units of measure were introduced in \PDFTEX\ 1.30.0: the new
4354 Didot ($\mbox{1nd}=0.375$mm) and the new Cicero ($\mbox{1nc}=12$nd). The
4355 former was proposed by \ISO\ in 1975.
4356
4357 \begingroup
4358 \parindent=0pt
4359 % because the summary is nothing but a long string of \Syntax
4360 % commands, we have to allow breaks, in contrast to the main text.
4361 \def\aftersyntax{\par\vskip 1.5pt plus1pt minus1pt\relax}
4362
4363 % Generated list of primitives (see Makefile).
4364 \input{incl/pdftex-syntax.tex}
4365
4366 \section{General definitions and syntax rules}
4367
4368 \Syntax{
4369 \Something{general text} \Means
4370 \Lbrace \Something{balanced text} \Rbrace
4371 }
4372
4373 \Syntax{
4374 \Something{attr spec} \Means
4375 \Literal{attr} \Something{general text}
4376 }
4377
4378 \Syntax{
4379 \Something{resources spec} \Means
4380 \Literal{resources} \Something{general text}
4381 }
4382
4383 \Syntax{
4384 \Something{rule spec} \Means
4385 (\Literal{width} \Or \Literal{height} \Or \Literal{depth})
4386 \Something{dimen} \Optional{\Something{rule spec}}
4387 }
4388
4389 \Syntax{
4390 \Something{object type spec} \Means
4391 \Literal{reserveobjnum}
4392 \Or\Next
4393 \Optional{\Literal{useobjnum} \Something{number}} \Next
4394 \Optional{\Literal{stream} \Optional{\Something{attr spec}}}
4395 \Something{object contents}
4396 }
4397
4398 \Syntax{
4399 \Something{annot type spec} \Means
4400 \Literal{reserveobjnum}
4401 \Or\Next
4402 \Optional{\Literal{useobjnum} \Something{number}}
4403 \Optional{\Something{rule spec}}
4404 \Something{general text}
4405 }
4406
4407 \Syntax{
4408 \Something{object contents} \Means
4409 \Something{file spec}
4410 \Or \Something{general text}
4411 }
4412
4413 \Syntax{
4414 \Something{image attrs} \Means
4415 \Optional{\Something{rule spec}}
4416 \Optional{\Something{attr spec}}
4417 \Optional{\Something{page spec}}
4418 \Optional{\Something{named spec}}
4419 \Optional{\Something{colorspace spec}}
4420 \Optional{\Something{pdf box spec}}
4421 }
4422
4423 \Syntax{
4424 \Something{outline spec} \Means
4425 \Optional{\Something{attr spec}}
4426 \Something{action spec}
4427 \Optional{\Literal{count} \Something{number}}
4428 \Something{general text}
4429 }
4430
4431 \Syntax{
4432 \Something{action spec} \Means
4433 \Literal{user} \Something{user-action spec}
4434 \Or \Literal{goto} \Something{goto-action spec}
4435 \Or \Literal{thread} \Something{thread-action spec}
4436 }
4437
4438 \Syntax{
4439 \Something{user-action spec} \Means
4440 \Something{general text}
4441 }
4442
4443 \Syntax{
4444 \Something{goto-action spec} \Means
4445 \Optional{\Something{goto-action struct spec}} \Something{numid}
4446 \Next\Or \Optional{\Something{file spec}} \Optional{\Something{goto-action struct spec}} \Something{nameid}
4447 \Next\Or \Optional{\Something{file spec}} \Optional{\Something{goto-action struct spec}}
4448 \Optional{\Something{page spec}} \Something{general text}
4449 \Next\Or \Something{file spec} \Optional{\Something{goto-action struct spec}}
4450 \Next\qquad \Optional{
4451 \Something{nameid}
4452 \Or \Something{page spec} \Something{general text}}
4453 \Next\qquad \Something{newwindow spec}
4454 }
4455
4456 \Syntax{
4457 \Something{goto-action struct spec} \Means
4458 \Literal{struct} \OneOf{\Something{numid} \Or \Something{nameid}
4459 \Or \Something{general text}}
4460 }
4461
4462 \Syntax{
4463 \Something{thread-action spec} \Means
4464 \Optional{\Something{file spec}} \Something{numid}
4465 \Or \Optional{\Something{file spec}} \Something{nameid}
4466 }
4467
4468 \Syntax{
4469 \Something{colorspace spec} \Means
4470 \Literal{colorspace} \Something{number}
4471 }
4472
4473 \Syntax{
4474 \Something{pdf box spec} \Means
4475 \Literal{mediabox}
4476 \Or \Literal{cropbox}
4477 \Or \Literal{bleedbox}
4478 \Or \Literal{trimbox}
4479 \Or \Literal{artbox}
4480 }
4481
4482 \Syntax{
4483 \Something{map spec} \Means
4484 \Lbrace \Optional{\Something{map modifier}}
4485 \Something{balanced text} \Rbrace
4486 }
4487
4488 \Syntax{
4489 \Something{map modifier} \Means
4490 \Literal{+} \Or \Literal{=} \Or \Literal{-}
4491 }
4492
4493 \Syntax{
4494 \Something{numid} \Means
4495 \Literal{num} \Something{number}
4496 }
4497
4498 \Syntax{
4499 \Something{nameid} \Means
4500 \Literal{name} \Something{general text}
4501 }
4502
4503 \Syntax{
4504 \Something{newwindow spec} \Means
4505 \Literal{newwindow} \Or \Literal{nonewwindow}
4506 }
4507
4508 \Syntax{
4509 \Something{dest spec} \Means
4510 \Optional{\Literal{struct} \Something{number}}
4511 \OneOf{\Something{numid} \Or \Something{nameid}}
4512 \Something{dest type}
4513 }
4514
4515 \Syntax{
4516 \Something{dest type} \Means
4517 \Literal{xyz} \Optional{\Literal{zoom} \Something{number}}
4518 \Or \Literal{fitr} \Something{rule spec}
4519 \Or \Next \Literal{fitbh}
4520 \Or \Literal{fitbv}
4521 \Or \Literal{fitb}
4522 \Or \Literal{fith}
4523 \Or \Literal{fitv}
4524 \Or \Literal{fit}
4525 }
4526
4527 \Syntax{
4528 \Something{thread spec} \Means
4529 \Optional{\Something{rule spec}}
4530 \Optional{\Something{attr spec}}
4531 \Something{id spec}
4532 }
4533
4534 \Syntax{
4535 \Something{id spec} \Means
4536 \Something{numid} \Or \Something{nameid}
4537 }
4538
4539 \Syntax{
4540 \Something{file spec} \Means
4541 \Literal{file} \Something{general text}
4542 }
4543
4544 \Syntax{
4545 \Something{page spec} \Means
4546 \Literal{page} \Something{number}
4547 }
4548
4549 \Syntax{
4550 \Something{named spec} \Means
4551 \Literal{named} \Something{general text}
4552 }
4553
4554 \Syntax{
4555 \Something{expand spec} \Means
4556 \Something{stretch}
4557 \Something{shrink}
4558 \Something{step}
4559 \Optional{\Literal{autoexpand}}
4560 }
4561
4562 \Syntax{
4563 \Something{stretch} \Means
4564 \Something{number}
4565 }
4566
4567 \Syntax{
4568 \Something{shrink} \Means
4569 \Something{number}
4570 }
4571
4572 \Syntax{
4573 \Something{step} \Means
4574 \Something{number}
4575 }
4576
4577 \Syntax{
4578 \Something{pre spec} \Means
4579 \Literal{pre}
4580 }
4581
4582 \Syntax{
4583 \Something{stack action} \Means
4584 \Literal{set} \Or \Literal{push} \Or \Literal{pop} \Or \Literal{current}
4585 }
4586
4587 \endgroup % of syntax definitions
4588
4589 \medskip
4590
4591 A \Something{general text} is expanded immediately, like \cs{special}
4592 in traditional \TEX, unless explicitly mentioned otherwise.
4593
4594 Some of the object and image-related primitives can be prefixed by
4595 \cs{immediate}.
4596
4597 \chapter{Abbreviations used in this manual}
4598
4599 In this document we use numerous abbreviations. For convenience we give
4600 their meanings here.
4601
4602 \abbrevlist
4603
4604 \twocolumn {\small \emergencystretch=1.5em \input{incl/fdl-1.2.tex}}
4605
4606 \end{document}