| 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} |