summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/pdftex/manual/pdftex-t.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/pdftex/manual/pdftex-t.tex')
-rw-r--r--Master/texmf-dist/doc/pdftex/manual/pdftex-t.tex1971
1 files changed, 652 insertions, 1319 deletions
diff --git a/Master/texmf-dist/doc/pdftex/manual/pdftex-t.tex b/Master/texmf-dist/doc/pdftex/manual/pdftex-t.tex
index e7a56202e9d..9ae584c7c5e 100644
--- a/Master/texmf-dist/doc/pdftex/manual/pdftex-t.tex
+++ b/Master/texmf-dist/doc/pdftex/manual/pdftex-t.tex
@@ -1,29 +1,11 @@
% interface=english modes=letter,screen output=pdftex
% vim: tw=79
-% $Id: pdftex-t.tex 722 2015-03-25 23:13:50Z karl $
+% $Id: pdftex-t.tex 745 2016-04-25 18:06:57Z karl $
-% The number of lines on the titlepage depends on exactly
+% The number of lines on the title page depends on exactly
% what \PDF\ code is generated.
-%
-\setvariables[pdftex][titlepagelines=55]
-
-%D We use a multi purpose style (using modes) that enable us
-%D to generate an A4, letter and screen version.
-%D
-%D Default A4 size manual:
-%D texexec --result=pdftex-a.pdf pdftex-t
-%D
-%D Letter size manual:
-%D texexec --mode=letter --result=pdftex-l.pdf pdftex-t
-%D
-%D Booklet (given that A4 document is available):
-%D texexec --pdfarrange --paper=a5a4 --print=up --addempty=1,2 --result=pdftex-b.pdf pdftex-a
-%D
-%D Screen version
-%D texexec --mode=screen pdftex-t
-
-%D This is the \PDFTEX\ manual, so it makes sense to force \PDF\ output here.
+\setvariables[pdftex][titlepagelines=64]
\setupoutput
[pdftex]
@@ -52,13 +34,13 @@
\def\rcsmonth{#5}
\def\rcsday{{\count0=#6\relax\the\count0}}
\def\rcsmonthname{\ifcase\rcsmonth ERROR\or
- January\or February\or March\or April\or May\or June\or
- July\or August\or September\or October\or November\or December\else ERROR\fi}
+ January\or February\or March\or April\or May\or June\or July\or
+ August\or September\or October\or November\or December\else ERROR\fi}
}
-\svnscan $Id: pdftex-t.tex 722 2015-03-25 23:13:50Z karl $
+\svnscan $Id: pdftex-t.tex 745 2016-04-25 18:06:57Z karl $
-\def\currentpdftex{1.40.16}
+\def\currentpdftex{1.40.17}
%***********************************************************************
@@ -68,8 +50,6 @@
\def\PDFReference{{\sl PDF Reference}} % PDF with capital letters
\abbreviation [AFM] {afm} {Adobe Font Metrics}
-%\abbreviation [AMIGA] {Amiga} {Amiga hardware platform}
-%\abbreviation [AMIWEB] {AmiWeb2c} {\AMIGA\ distribution}
\abbreviation [BIBTEX] {Bib\TeX} {Handles bibliographies}
\abbreviation [ASCII] {ascii} {American Standard Code for Information Interchange}
\abbreviation [CONTEXT] {\ConTeXt} {general purpose macro package}
@@ -151,7 +131,9 @@
\useURL [ptex_bugs] [mailto:pdftex@tug.org] [] [pdftex@tug.org]
\useURL [ptex_listinfo] [http://lists.tug.org/pdftex]
-\useURL [texlive] [http://tug.org/texlive/]
+\useURL [kpathsea] [http://tug.org/kpathsea]
+\useURL [texlive] [http://tug.org/texlive]
+\useURL [web2c] [http://tug.org/web2c]
\useURL [ctan_systems] [http://mirror.ctan.org/systems]
\useURL [win32] [http://mirror.ctan.org/systems/win32]
\useURL [context] [http://www.pragma-ade.com]
@@ -170,24 +152,26 @@
\let\ifpdfabsnum\relax
\let\ifpdfabsdim\relax
+\def\Syntax #1{\strut\kern-.25em{#1}\kern-.25em}
+\def\Next {\crlf\hbox to 2em{}\nobreak}
\def\Sugar #1{\unskip\unskip\unskip\kern.25em{#1}\kern.25em\ignorespaces}
-\def\Something#1{\Sugar{\mathematics{\langle\hbox{#1}\rangle}}}
+%
\def\Lbrace {\Sugar{\tttf\leftargument}}
-\def\Rbrace {\Sugar{\tttf\rightargument}}
-\def\Or {\Sugar{\mathematics{\vert}}}
-\def\Optional #1{\Sugar{\mathematics{[\hbox{#1}]}}}
+\def\Literal #1{\Sugar{\type{#1}}}
\def\Means {\Sugar{\mathematics{\rightarrow}}}
+\def\Modelist #1{\Sugar{\mathematics{(\hbox{#1})}}}
+\def\Optional #1{\Sugar{\mathematics{[\hbox{#1}]}}}
+\def\Or {\Sugar{\mathematics{\vert}}}
+\def\Rbrace {\Sugar{\tttf\rightargument}}
\def\Tex #1{\Sugar{\type{#1}}}
-\def\Literal #1{\Sugar{\type{#1}}}
-\def\Syntax #1{\strut\kern-.25em{#1}\kern-.25em}
-\def\Next {\crlf\hbox to 2em{}\nobreak}
\def\Whatever #1{\Sugar{\mathematics{(\hbox{#1})}}}
% hyphenates
-
\def\Something#1{\Sugar{\mathematics{\langle}\prewordbreak
{#1}\prewordbreak\mathematics{\rangle}}}
+\hbadness=10000 % don't care
+
% Break after these chars in urls, not before.
\sethyphenatedurlafter /
\sethyphenatedurlafter .
@@ -395,7 +379,7 @@
color=,
page=yes,
openaction=firstpage,
- title=the pdfTeX users manual,
+ title=pdfTeX users manual,
author={H\`an Th\^e Th\`anh, Sebastian Rahtz, Hans Hagen, Hartmut Henkel,
Pawe\l\ Jackowski, Martin Schr\"oder, Karl Berry}]
@@ -542,13 +526,14 @@
\start
\chardef\fontdigits=2
- \switchtobodyfont[12pt,tt]
- \setupinterlinespace[line=\dimexpr((\paperheight-1cm)/\getvariable{pdftex}{titlepagelines})]
+ \switchtobodyfont[10pt,tt]
+ \setupinterlinespace
+ [line=\dimexpr((\paperheight-1cm)/\getvariable{pdftex}{titlepagelines})]
\setuptyping[margin=,color=]
\setuplayout[titlepage]
\startcolumnset[titlepage]
- \typefile{pdftex-t.txt}
+ \typefile{pdftex-w.txt}
\stopcolumnset
\page
@@ -684,10 +669,10 @@ bug reports to the mailing list \from [ptex_bugs] (\from [ptex_listinfo]).
\subsection{About this manual}
-This manual revision (\rcsrevision) is intended to track current
-\PDFTEX\ development, up to version \currentpdftex. The primary
+This manual revision (\rcsrevision) is intended to cover
+\PDFTEX\ development up to version \currentpdftex. The primary
repository for the manual and its sources is at \from[ptex_devel].
-Copies in \PDF\ format can also be found on \CTAN\ in \from[ptex_ctan].
+Copies in \PDF\ format can also be found on \CTAN\ via \from[ptex_ctan].
Thanks to the many people who have contributed to the manual.
New errors might have slipped in afterwards by the editor.
@@ -697,7 +682,7 @@ Please send questions or suggestions by email to \from[ptex_bugs].
\subsection{Legal Notice}
-Copyright \copyright\ 1996||2015 \THANH.
+Copyright \copyright\ 1996||2016 \THANH.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2
or any later version published by the Free Software Foundation;
@@ -732,13 +717,13 @@ objects by new ones.
When a viewer opens a \PDF\ file, it goes to the end of the file,
looking for the keyword \type{startxref}. The number after
\type{startxref} gives the absolute position (byte offset from the file
-start) of the so called \quote {object cross-reference table} that
+start) of the so||called \quote {object cross-reference table} that
begins with the keyword \type{xref}. This table in turn tells the byte
offsets of all objects that make up the \PDF\ file, providing fast
random access to the individual objects (here the \type{xref} table
shows 11~objects, numbered from~0 to~10; the object no.~0 is always
unused). The actual starting point of the file's object structure is
-defined after the \type{trailer}: The \type{/Root} entry points to the
+defined after the \type{trailer}: the \type{/Root} entry points to the
\type{/Catalog} object (no.~9). In this object the viewer can find the
pointer \type{/Pages} to the page list object (no.~5). In our example we
have only one page. The trailer also holds an \type{/Info} entry, which
@@ -758,7 +743,7 @@ take a look at the \PDF\ code of this file to get an impression of that.
The page content is a stream of drawing operations. Such a stream
can be compressed, where the level of compression can be set with
-\type {\pdfcompresslevel} (compression is switched off for the title
+\type{\pdfcompresslevel} (compression is switched off for the title
page). Let's take a closer look at this stream in object~3. Often
(but not in our example) there is a transformation matrix, six numbers
followed by \type{cm}. As in \POSTSCRIPT, the operator comes after the
@@ -792,27 +777,23 @@ therefore need not be embedded in the \PDF\ file, it is left out here
for brevity. However, when we use for instance a Computer Modern Roman
font, we have to make sure that this font is later available to the \PDF\
viewer, and the best way to do this is to embed the font.
-
-It's highly recommended nowadays to embed even the standard fonts, as
-modern viewers often don't use the original 14~standard fonts anymore,
-but instead approximate them by instances of built||in Multiple Master
-fonts (\eg\ the Adobe Reader~7 approximates the Times-Roman variants by
-the Minion font). So you never really know how it looks exactly at the
-viewer side unless you embed every font.
+It's highly recommended nowadays to embed even the standard fonts;
+you can't know how it looks exactly at the viewer side unless you embed
+every font.
In this simple file we don't specify in what way the file should be opened,
for instance full screen or clipped. A closer look at the page object no.~2
(\typ{/Type /Page}) shows that a mediabox (\typ{/MediaBox}) is part of the
page description. A mediabox acts like the (high-resolution) bounding box
in a \POSTSCRIPT\ file. \PDFTEX\ users can add dictionary stuff to page
-objects by the \type{\pdfpageattr} primitive.
+objects with the \type{\pdfpageattr} primitive.
Although in most cases macro packages will shield users from these
internals, \PDFTEX\ provides access to many of the entries described
here, either automatically by translating the \TEX\ data structures into
\PDF\ ones, or manually by pushing entries to the catalog, page, info or
self-created objects. One can for instance create an object by using
-\type{\pdfobj} after which \type{\pdflastobj} returns its number. So
+\type{\pdfobj}, after which \type{\pdflastobj} returns its number. So
\starttyping
\pdfobj{<< /Type/ExtGState /LW 2 >>}
@@ -829,14 +810,13 @@ by primitives like \type{\pdfobj} is not very useful, and only makes
sense when implementing, say, fill||in field support or annotation
content reuse. We will come to that later.
-For those who want to learn more about the gory \PDF\ details, the best
-bet is to read the \PDFReference. As of the time of writing you can
-download this book as a big \PDF\ file from Adobe's \PDF\ Technology Center,
+Of course, this is just the barest introduction to \PDF\ format. For
+those who want to learn more about the gory \PDF\ details, the best bet
+is to read the \PDFReference. As of the time of writing you can download
+this book as a big \PDF\ file from Adobe's \PDF\ Technology Center,
\from[pdfreference] --- or get the heavy paper version.
-Those who, after this introduction, feel unsure how to proceed, are
-advised to read on but skip \in{section}[primitives]. Before we come to
-that section, we will describe how to get started with \PDFTEX.
+We now turn to specifics of \PDFTEX.
%***********************************************************************
@@ -845,7 +825,7 @@ that section, we will describe how to get started with \PDFTEX.
This section describes the steps needed to get \PDFTEX\ running on
a system where \PDFTEX\ is not yet installed. Nowadays virtually all
\TEX\ distributions have \PDFTEX\ as a component, such as \TEXLIVE,
-\TETEX, \XEMTEX, \MIKTEX, \PROTEXT, and \MACTEX. The ready to run
+\MIKTEX, \TETEX, \XEMTEX, \PROTEXT, and \MACTEX. The ready to run
\TEXLIVE\ distribution comes with \PDFTEX\ versions for many \UNIX,
\WIN, and \MACOSX\ systems; more information can be found at
\hbox{\from[texlive].} There are also \WIN-specific distributions which
@@ -866,15 +846,12 @@ is \WEBC||specific.
\subsection{Getting sources and binaries}
-The latest sources of \PDFTEX\ are distributed for compilation
-on \UNIX\ systems (including \GNU/Linux), and \WIN\ systems. The
-primary home page is \from[ptex_org], where you also find bug tracking
-information. Development sources are at \from[ptex_devel].
-
-The \PDFTEX\ sources can also be found at their canonical place in the
-\CTAN\ network, \from[ptex_ctan]. Precompiled \PDFTEX\ binaries for
-various systems might also be available, check the subdirectories
-below \from[ctan_systems].
+The latest sources of \PDFTEX\ are distributed for compilation on \UNIX\
+systems (including \GNU/Linux), and \WIN\ systems. The primary home
+page is \from[ptex_org], where you also find bug tracking information.
+Development sources are at \from[ptex_devel]. Precompiled \PDFTEX\
+binaries for various systems might be available in subdirectories below
+\from[ctan_systems], or via \TEX\ distribution web pages.
%***********************************************************************
@@ -935,13 +912,13 @@ relative to the place of the \PDFTEX\ binary; on a \TEXLIVE\ system,
file \filename{texmf.cnf} can also be set up by the environment variable
\type{TEXMFCNF}.
-Next you might need to edit \filename {texmf.cnf} so that \PDFTEX\
-can find all necessary files, but the \filename{texmf.cnf} files
-coming with the major \TEX\ distributions should already be set up for
-normal use. You might check into the file \filename{texmf.cnf} to see
-where the various bits and pieces are going.
+The \filename{texmf.cnf} files coming with the major \TEX\ distributions
+should already be set up for normal use, so you shouldn't need to edit
+it. You might still like to read it to see where the various bits and
+pieces are going.
-\PDFTEX\ uses the search path variables shown in \in{table}[tbl:spathvar].
+\PDFTEX\ uses the search path variables shown in
+\in{table}[tbl:spathvar], among others.
\startbuffer
\starttabulate[|l|l|]
@@ -959,23 +936,23 @@ where the various bits and pieces are going.
\NC Type~1 fonts \NC \type{T1FONTS} \NC\NR
\NC TrueType fonts \NC \type{TTFONTS} \NC\NR
\NC OpenType fonts \NC \type{OPENTYPEFONTS} \NC\NR
-\NC pixel fonts \NC \type{PKFONTS} \NC\NR
+\NC bitmap fonts \NC \type{PKFONTS} \NC\NR
\HL
\stoptabulate
\stopbuffer
\placetable[here][tbl:spathvar]
- {The \WEBC\ variables.}
+ {The principal \WEBC\ variables.}
{\getbuffer}
\PathDescription {TEXMFOUTPUT} Normally, \PDFTEX\ puts its output files
-in the current directory. If any output file cannot be opened there, it
-tries to open it in the directory specified in the environment variable
-\type{TEXMFOUTPUT}. There is no default value for that variable. For
-example, if you type \type{pdftex paper} and the current directory is
-not writable, if \type{TEXMFOUTPUT} has the value \type{/tmp}, \PDFTEX\
-attempts to create \type{/tmp/paper.log} (and \type{/tmp/paper.pdf},
-if any output is produced.)
+in the current directory, overridden by the \type{-output-directory}
+option. If any output file cannot be opened there, it tries to open it
+in the environment variable \type{TEXMFOUTPUT}, if that is set. There is
+no default value for that variable. For example, if \type{TEXMFOUTPUT}
+has the value \type{/tmp}, and you run \type{pdftex paper} when the
+current directory is not writable, \PDFTEX\ attempts to create
+\type{/tmp/paper.log} (and \type{/tmp/paper.pdf}, etc.)
\PathDescription {TEXINPUTS} This variable specifies where \PDFTEX\ finds
its input files. Image files are considered
@@ -1014,17 +991,24 @@ viewers, so when possible one should use outline fonts. When no outline
is available, \PDFTEX\ tries to locate a suitable \PK\ font (or invoke
a process that generates it).
+\PathDescription{TEXFONTS} Fallback for all the font paths, so that if
+you want to look in a particular directory for fonts on a given run, you
+can set that one variable.
+
+Many more variables may be consulted, and there are many details to
+file name lookups. See the Kpathsea manual (\from [kpathsea]).
+
%***********************************************************************
\subsection[cfg]{The \PDFTEX\ configuration}
-One has to keep in mind that, as opposed to \TEX\ with its \DVI\ output,
-the \PDFTEX\ program does not require a separate postprocessing stage
-to transform the \TEX\ input into a \PDF\ file. As a consequence, all
-data needed for building a ready \PDF\ page must be available
-during the \PDFTEX\ run, in particular information on media dimensions
-and offsets, graphics files for embedding, and font information (font
-files, encodings).
+We must keep in mind that, as opposed to \TEX\ with its \DVI\ output,
+the \PDFTEX\ program does not have a separate postprocessing stage to
+transform the \TEX\ input into final \PDF. As a consequence, all data
+needed for building a ready \PDF\ page must be available during the
+\PDFTEX\ run, in particular information on media dimensions and offsets,
+graphics files for embedding, and font information (font files,
+encodings).
When \TEX\ builds a page, it places items relative to the top left page
corner (the \DVI\ reference point). Separate \DVI\ postprocessors allow
@@ -1104,31 +1088,33 @@ even without setting any parameters.
\tx\setupinterlinespace
\startframedtext
\starttyping
-% Set pdfTeX parameters for pdf mode (replacing pdftex.cfg file).
-% Thomas Esser, 2004. public domain.
-\pdfoutput=1
-\pdfcompresslevel=9
-\pdfdecimaldigits=3
-\pdfpagewidth=210 true mm
-\pdfpageheight=297 true mm
-\pdfhorigin=1 true in
-\pdfvorigin=1 true in
-\pdfpkresolution=600
-%
-% As of TeX Live 2010, we output PDF 1.5 by default, so we can enable
-% more compression. To change this for the installation, comment out or
-% delete these lines and remake the formats. To change it for a
-% particular LaTeX document, \RequirePackage{pdf14} early.
-%
-\pdfminorversion=5
-\pdfobjcompresslevel=2
-\endinput
+% tex-ini-files 2016-04-15: pdftexconfig.tex
+
+% Load shared (PDF) settings in pdfTeX
+
+% Enable PDF output
+\pdfoutput = 1
+
+% Paper size: dimensions given in absolute terms
+\pdfpageheight = 11 true in
+\pdfpagewidth = 8.5 true in
+
+% Enable PDF 1.5 output and thus more compression
+\pdfminorversion = 5
+\pdfobjcompresslevel = 2
+
+% Low-level settings unlikely ever to need to change
+\pdfcompresslevel = 9
+\pdfdecimaldigits = 3
+\pdfpkresolution = 600
+\pdfhorigin = 1 true in
+\pdfvorigin = 1 true in
\stoptyping
\stopframedtext
\stopbuffer
\placefigure[here][in:pdftexconfig]
- {The \PDFTEX\ configuration file for \TEXLIVE\ (\filename{pdftexconfig.tex}).}
+ {\PDFTEX\ configuration file for \TEXLIVE\ (\filename{pdftexconfig.tex}).}
{\getbuffer}
Independent of whether such a configuration file is read or not, the
@@ -1145,15 +1131,7 @@ memory layout (\eg\ string pool and hash size), and other general parameters.
\tx\setupinterlinespace
\startframedtext
\starttyping
-% Thomas Esser, 1998, 2004. public domain.
-\ifx\pdfoutput\undefined
-\else
- \ifx\pdfoutput\relax
- \else
- \input pdftexconfig
- \pdfoutput=0
- \fi
-\fi
+% Thomas Esser, 1998. public domain.
\input etex.src
\dump
\endinput
@@ -1162,21 +1140,35 @@ memory layout (\eg\ string pool and hash size), and other general parameters.
\stopbuffer
\placefigure[here][in:etexini]
- {File \type{etex.ini} for \ETEX\ format with \DVI\ output.}
+ {File \type{etex.ini} for the plain \ETEX\ format with \DVI\ output.}
{\getbuffer}
\startbuffer
\tx\setupinterlinespace
\startframedtext
\starttyping
-\ifx\pdfoutput\undefined
-\else
- \ifx\pdfoutput\relax
- \else
- \input pdftexconfig
- \pdfoutput=1
- \fi
-\fi
+% Thomas Esser, 1998. public domain.
+% This is used for pdftex and pdfetex, which are now identical: both
+% with e-TeX extensions, both with pdf output.
+\input pdftexconfig.tex
+\input etex.src
+\input pdftexmagfix.tex
+\dump
+\endinput
+\stoptyping
+\stopframedtext
+\stopbuffer
+
+\placefigure[here][in:pdfetexini]
+ {File \type{pdfetex.ini} for plain \ETEX\ with \PDF\ output.}
+ {\getbuffer}
+
+\startbuffer
+\tx\setupinterlinespace
+\startframedtext
+\starttyping
+% Thomas Esser, 1998. public domain.
+\input pdftexconfig.tex
\scrollmode
\input latex.ltx
\endinput
@@ -1185,104 +1177,85 @@ memory layout (\eg\ string pool and hash size), and other general parameters.
\stopbuffer
\placefigure[here][in:pdflatexini]
- {File \type{pdflatex.ini} for \LATEX\ format with \PDF\ output.}
+ {File \type{pdflatex.ini} for the \LATEX\ format with \PDF\ output.}
{\getbuffer}
-The \PDFTEX\ engine allow building formats for \DVI\ and
-\PDF\ output in the same way as the classical \TEX\ engine does for \DVI.
-Format generation is enabled by the \type{-ini} option. The default mode
-(\DVI\ or \PDF) can be chosen either on the command line by setting
-the option \type{-output-format} to \type{dvi} or \type{pdf}, or by
-setting the \type{\pdfoutput} parameter. The format file then inherits
-this setting, so that a later call to \PDFTEX\ with this format starts
-in the preselected mode (which still can be overrun then). A format
-file can be read in only by the engine that has generated it; a format
-incompatible with an engine leads to a fatal error.
+The \PDFTEX\ engine supports building formats for \DVI\ and \PDF\ output
+in the same way as the classical \TEX\ engine does for \DVI. Format
+generation is enabled by the \type{-ini} option. The default mode (\DVI\
+or \PDF) can be chosen either on the command line by setting the option
+\type{-output-format} to \type{dvi} or \type{pdf}, or by setting the
+\type{\pdfoutput} parameter. The format file then inherits this setting,
+so that a later invocation of \PDFTEX\ with this format starts in the
+preselected mode (which still can be overridden). A format file can be
+read in only by the engine that has generated it; a format incompatible
+with an engine leads to a fatal error.
It is customary to package the configuration and macro file input
into a \type{.ini} file. \Eg, the file \type{etex.ini} in
\in{figure}[in:etexini] is for generating an \ETEX\ format with \DVI\
-output (it contains a few comparisons to be safe also for \TEX\ engines).
-A similar file \type{pdflatex.ini} can be used for generating a \LATEX\
-format with \PDF\ output; refer to \in{figure}[in:pdflatexini].
-One can see how the primitive \type{\pdfoutput} is used to override
-the output mode set by file \type{pdftexconfig.tex}. The corresponding
-\PDFTEX\ calls for format generation are:
+output. It has been traditional for many years to generate
+\type{etex.fmt} with \PDFTEX\ rather than the original \ETEX, because
+\PDFTEX\ contains a few additional programming and other
+non-\PDF-related features on which people have come to rely.
-\starttyping
-pdftex -ini *etex.ini
-pdftex -ini pdflatex.ini
-\stoptyping
+The \type{pdfetex.ini} file \in{figure}[in:etexini] shows the
+corresponding format with \PDF\ output by default; this is what creates
+the format file read when \type{pdftex} is normally invoked.
-These calls produce format files \filename{etex.fmt} and
-\filename{pdflatex.fmt}, as the default format file name is taken from
-the input file name. You can overrule this with the \type{-jobname}
-option. The asterisk \type{*} in the first example line below tells the
-\PDFTEX\ engine to go into extended \type{-ini} mode (\ETEX\ enabled);
-otherwise it stays in non||extended \type{-ini} mode. The extended
-\type{-ini} mode can also be forced by the \type{-etex} command line
-option, as shown in the 2nd line below.
+Finally, \type{pdflatex.ini} \in{figure}[in:pdflatexini] shows how the
+\LATEX\ format with \PDF\ output by default is generated.
-\starttyping
-pdftex -ini -jobname=pdfelatex *pdflatex.ini
-pdftex -ini -jobname=pdfelatex -etex pdflatex.ini
-\stoptyping
-
-In \CONTEXT\ the generation depends on the interface used. A format using the
-English user interface is generated with
+The corresponding \PDFTEX\ calls for format generation are:
\starttyping
-pdftex -ini cont-en
-\stoptyping
-
-When properly set up, one can also use the \CONTEXT\ command line interface
-\TEXEXEC\ to generate one or more formats, like:
-
-\starttyping
-texexec --make en
+pdftex -ini *etex.ini
+pdftex -ini *pdfetex.ini
+pdftex -ini *pdflatex.ini
\stoptyping
-for an English format, or
+These calls produce format files \filename{etex.fmt},
+\filename{pdfetex.fmt}, and \filename{pdflatex.fmt}, as the default
+format file name is taken from the input file name. You can overrule
+this with the \type{-jobname} option. The asterisk \type{*} before the
+file name is a unusual feature, only in \type{-ini} mode, which causes
+the \PDFTEX\ engine to enable \ETEX\ features.
-\starttyping
-texexec --make en de
-\stoptyping
+\subsection{Testing the installation}
-for an English and German one. Most \CONTEXT\ users will simply say:
+When everything is set up, you can test the installation. A simple test
+of plain \PDFTEX\ is:
\starttyping
-texexec --make --all [--alone]
+pdftex story \\end
\stoptyping
-and so generate the \TEX\ and \METAPOST\ related formats that \CONTEXT\
-needs. Whatever macro package used, the formats should be placed in the \type
-{TEXFORMATS} path.
-
-\subsection{Testing the installation}
+This should typeset the famous one-page short story by A.U. Thor.
-When everything is set up, you can test the installation. In the
-distribution there is a plain \TEX\ test file \filename{samplepdf.tex}
-in the \type{manual/samplepdf/} directory. Process this file by typing:
+A more thorough and descriptive test is the plain \TEX\ test file
+\filename{samplepdf.tex}, available in the distribution in the
+\type{samplepdftex/} directory. Process this file by typing:
\starttyping
pdftex samplepdf
\stoptyping
-If the installation is ok, this run should produce a file called
-\filename{samplepdf.pdf}. The file \filename {samplepdf.tex} is also
-a good place to look for how to use \PDFTEX's primitives.
+If the installation is ok, this should produce a file called
+\filename{samplepdf.pdf}. The file \filename {samplepdf.tex} is a good
+place to look for examples of how to use \PDFTEX's primitives.
%***********************************************************************
\subsection{Common problems}
-The most common problem with installations is that \PDFTEX\ complains that
-something cannot be found. In such cases make sure that \type{TEXMFCNF} is
-set correctly, so \PDFTEX\ can find \filename {texmf.cnf}. The next best
-place to look|/|edit is the file \type{texmf.cnf}. When still in deep
-trouble, set \type{KPATHSEA_DEBUG=255} before running \PDFTEX\ or run
-\PDFTEX\ with option \type{-k 255}. This will cause \PDFTEX\ to write a lot
-of debugging information that can be useful to trace problems. More options
+The most common problem with installations is that \PDFTEX\ complains
+that something cannot be found. In such cases make sure that
+\type{TEXMFCNF} is set correctly, so \PDFTEX\ can find \filename
+{texmf.cnf}. The next best place to look|/|edit is the file
+\type{texmf.cnf}. When still in deep trouble, set
+\type{KPATHSEA_DEBUG=255} before running \PDFTEX\ or use the option
+\type{-kpathsea-debug 255}. This will cause \PDFTEX\ to write a lot of
+debugging information that can be useful to trace problems. More options
can be found in the \WEBC\ documentation.
Variables in \filename {texmf.cnf} can be overwritten by environment
@@ -1299,8 +1272,7 @@ getting started:
\filename {texmf.cnf} contains the path to \filename {pdftex.fmt}
or \filename {pdflatex.fmt}.
-\head \type{---! xx.fmt was written by tex} \crlf
- \type{Fatal format file error; I'm stymied}
+\head \type{Fatal format file error; I'm stymied}
This appears \eg\ if you forgot to regenerate the \type{.fmt}
files after installing a new version of the \PDFTEX\ binary.
@@ -1332,6 +1304,42 @@ the object table size is now obsolete and ignored).
%***********************************************************************
+\section{Invoking \PDFTEX}
+
+\PDFTEX\ has many command line options. With the exception of the
+simple and rarely-used \type{-draftmode} and \type{-output-format}
+options, they are all inherited from the common framework for \TeX\
+engines as implemented in \WEBC\ (\from [web2c] has the manual).
+
+The same commonality holds for environment variables; see the section
+``Setting search paths'' above for an overview. However, \PDFTEX\ looks
+for one additional environment variable: \type{SOURCE_DATE_EPOCH}
+(introduced in version 1.40.17, 2016). If this is set, it must be a
+positive integer (with one trivial exception: if it is set but empty,
+that is equivalent to 0). Non-integer values cause a fatal error. The
+value is used as the current time in seconds since the usual Unix
+``epoch'', the beginning of 1970-01-01, UTC. Thus, a value of \type{32}
+would result in a \type{/CreationDate} and \type{/ModDate} values of
+\type{19700101000032Z}. This is useful for reproducible builds of
+documents. (See also \type{\pdfinfoomitdate},
+\type{\pdfsuppressptexinfo}, et al.)
+
+Just to have the list of options and basic invocation at hand, here is a
+verbatim listing of the \type{-}\type{-help} output. All options can be
+specified with one or two dashes and unambiguously abbreviated.
+
+\startnotmode[screen]
+ \switchtobodyfont[9pt] % squeeze everything on one page
+\stopnotmode
+
+\typefile{pdftex-help.txt}
+
+\startnotmode[screen]
+ \switchtobodyfont[10pt] % squeeze everything on one page
+\stopnotmode
+
+%***********************************************************************
+
\section{Macro packages supporting \PDFTEX}
As \PDFTEX\ generates the final \PDF\ output without help of
@@ -1388,7 +1396,7 @@ to turn on \PDFTEX\ support explicitly.
for \PDFTEX\ in its generalized hypertext features. Support for
\PDFTEX\ is implemented as a special driver, and is invoked by
typing \type{\setupoutput[pdftex]} or feeding \TEXEXEC\ with the
- \type{--pdf} option.
+ \type{-{}-pdf} option.
\item \PDF\ from \TEXINFO\ documents can be created by running \PDFTEX\ on
the \TEXINFO\ file, instead of \TEX. Alternatively, run the shell
@@ -1650,11 +1658,10 @@ which tells how to handle the font file:
When one suffers from invalid lookups, for instance when \PDFTEX\ tries
to open a \type{.pfa} file instead of a \type{.pfb} one, one can add
the suffix to the filename. In this respect, \PDFTEX\ completely relies
-on the \type{kpathsea} libraries.
+on the \type{kpathsea} library.
\stopdescription
-%HE Huh? pgc?
If a used font is not present in the map files, first \PDFTEX\ will
look for a source with suffix \type{.pgc}, which is a so||called \PGC\
source (\PDF\ Glyph Container) \footnote {This is a text file containing
@@ -1799,684 +1806,51 @@ on handling glyph names, see ``A closer look at TrueType fonts and
\section{Formal syntax specification}
-This section formally specifies the \PDFTEX\ specific extensions to
-the \TEX\ macro programming language. Most primitives are prefixed
-by \type{pdf}.
-%All primitives are prefixed by
-%\type {pdf} except for \type{\efcode}, \type{\lpcode}, \type{\rpcode},
-%\type{\leftmarginkern}, \type{\rightmarginkern}, \type{\letterspacefont}
-%and the new conditionals (which begin with \type{ifpdf}).
-The general definitions and syntax rules follow after the list of primitives.
+This section formally specifies the \PDFTEX-specific extensions to the
+\TEX\ macro programming language. Most primitives are prefixed by
+\type{pdf}. The general definitions and syntax rules follow after the
+list of primitives.
Two new units of measure were introduced in \PDFTEX\ 1.30.0: the
new Didot (1\,nd~=~0.375\,mm) and the new Cicero (1\,nc~=~12\,nd)
(the former was proposed by \ISO\ in 1975).
-%%S This is the list of new or extended primitives provided by pdftex.
-%%S Don't edit this file, as it is now auto-generated from the
-%%S pdfTeX documentation file pdftex-t.tex by script syntaxform.awk.
-%%S Used convention for syntax rules is borrowed from `TeXbook naruby'
-%%S by Petr Olsak.
-%%S $Id: pdftex-t.tex 722 2015-03-25 23:13:50Z karl $
-%%S NL
-%%S integer registers:
-
-\subsubject{Integer registers}
-
-\startpacked
-
-\Syntax {
-\Tex {\pdfoutput} \Whatever{integer}
-}
-
-\Syntax {
-\Tex {\pdfminorversion} \Whatever{integer}
-}
-
-%\Syntax {
-%\Tex {\pdfoptionpdfminorversion} \Whatever{integer}
-%}
-
-\Syntax {
-\Tex {\pdfcompresslevel} \Whatever{integer}
-}
-
-\Syntax {
-\Tex {\pdfobjcompresslevel} \Whatever{integer}
-}
-
-\Syntax {
-\Tex {\pdfdecimaldigits} \Whatever{integer}
-}
-
-\Syntax {
-\Tex {\pdfimageresolution} \Whatever{integer}
-}
-
-\Syntax {
-\Tex {\pdfpkresolution} \Whatever{integer}
-}
-
-\Syntax {
-\Tex {\pdftracingfonts} \Whatever{integer}
-}
-
-\Syntax {
-\Tex {\pdfuniqueresname} \Whatever{integer}
-}
-
-\Syntax {
-\Tex {\pdfadjustspacing} \Whatever{integer}
-}
-
-\Syntax {
-\Tex {\pdfprotrudechars} \Whatever{integer}
-}
-
-\Syntax {
-\Tex {\efcode} \Something{font} \Something{8-bit number} \Whatever{integer}
-}
-
-\Syntax {
-\Tex {\lpcode} \Something{font} \Something{8-bit number} \Whatever{integer}
-}
-
-\Syntax {
-\Tex {\rpcode} \Something{font} \Something{8-bit number} \Whatever{integer}
-}
-
-\Syntax {
-\Tex {\pdfadjustinterwordglue} \Whatever{integer}
-}
-
-\Syntax {
-\Tex {\knbscode} \Something{font} \Something{8-bit number} \Whatever{integer}
-}
-
-\Syntax {
-\Tex {\stbscode} \Something{font} \Something{8-bit number} \Whatever{integer}
-}
-
-\Syntax {
-\Tex {\shbscode} \Something{font} \Something{8-bit number} \Whatever{integer}
-}
-
-\Syntax {
-\Tex {\pdfprependkern} \Whatever{integer}
-}
-
-\Syntax {
-\Tex {\knbccode} \Something{font} \Something{8-bit number} \Whatever{integer}
-}
-
-\Syntax {
-\Tex {\pdfappendkern} \Whatever{integer}
-}
-
-\Syntax {
-\Tex {\knaccode} \Something{font} \Something{8-bit number} \Whatever{integer}
-}
-
-\Syntax {
-\Tex {\pdfgentounicode} \Whatever{integer}
-}
-
-\Syntax {
-\Tex {\tagcode} \Something{font} \Something{character code} \Whatever{integer}
-}
-
-\Syntax {
-\Tex {\pdfpagebox} \Whatever{integer}
-}
-
-\Syntax {
-\Tex {\pdfforcepagebox} \Whatever{integer}
-}
-
-\Syntax {
-\Tex {\pdfoptionalwaysusepdfpagebox} \Whatever{integer}
-}
-
-\Syntax {
-\Tex {\pdfinclusionerrorlevel} \Whatever{integer}
-}
-
-\Syntax {
-\Tex {\pdfoptionpdfinclusionerrorlevel} \Whatever{integer}
-}
-
-\Syntax {
-\Tex {\pdfimagehicolor} \Whatever{integer}
-}
-
-\Syntax {
-\Tex {\pdfimageapplygamma} \Whatever{integer}
-}
-
-\Syntax {
-\Tex {\pdfgamma} \Whatever{integer}
-}
-
-\Syntax {
-\Tex {\pdfimagegamma} \Whatever{integer}
-}
-
-
-\Syntax {
-\Tex {\pdfinclusioncopyfonts} \Whatever{integer}
-}
-
-\Syntax {
-\Tex {\pdfdraftmode} \Whatever{integer}
-}
-
-\Syntax {
-\Tex {\pdfsuppresswarningdupdest} \Whatever{integer}
-}
-
-\Syntax {
-\Tex {\pdfsuppresswarningdupmap} \Whatever{integer}
-}
-
-\Syntax {
-\Tex {\pdfsuppresswarningpagegroup} \Whatever{integer}
-}
-
-\stoppacked
-
-%%S NL
-%%S dimen registers:
-
-\subsubject{Dimen registers}
-
-\startpacked
-
-\Syntax {
-\Tex {\pdfhorigin} \Whatever{dimen}
-}
-
-\Syntax {
-\Tex {\pdfvorigin} \Whatever{dimen}
-}
-
-\Syntax {
-\Tex {\pdfpagewidth} \Whatever{dimen}
-}
-
-\Syntax {
-\Tex {\pdfpageheight} \Whatever{dimen}
-}
-
-\Syntax {
-\Tex {\pdfignoreddimen} \Whatever{dimen}
-}
-
-\Syntax {
-\Tex {\pdffirstlineheight} \Whatever{dimen}
-}
-
-\Syntax {
-\Tex {\pdflastlinedepth} \Whatever{dimen}
-}
-
-\Syntax {
-\Tex {\pdfeachlineheight} \Whatever{dimen}
-}
-
-\Syntax {
-\Tex {\pdfeachlinedepth} \Whatever{dimen}
-}
-
-\Syntax {
-\Tex {\pdflinkmargin} \Whatever{dimen}
-}
-
-\Syntax {
-\Tex {\pdfdestmargin} \Whatever{dimen}
-}
-
-\Syntax {
-\Tex {\pdfthreadmargin} \Whatever{dimen}
-}
-
-\Syntax {
-\Tex {\pdfpxdimen} \Whatever{dimen}
-}
-
-\stoppacked
-
-%%S NL
-%%S token registers:
-
-\subsubject{Token registers}
-
-\startpacked
-
-\Syntax {
-\Tex {\pdfpagesattr} \Whatever{tokens}
-}
-
-\Syntax {
-\Tex {\pdfpageattr} \Whatever{tokens}
-}
-
-\Syntax {
-\Tex {\pdfpageresources} \Whatever{tokens}
-}
-
-\Syntax {
-\Tex {\pdfpkmode} \Whatever{tokens}
-}
-
-\stoppacked
-
-%%S NL
-%%S expandable commands:
-
-\subsubject{Expandable commands}
-
-\startpacked
-
-\Syntax {
-\Tex {\pdftexrevision} \Whatever{expandable}
-}
-
-\Syntax {
-\Tex {\pdftexbanner} \Whatever{expandable}
-}
-
-\Syntax {
-\Tex {\pdfcreationdate} \Whatever{expandable}
-}
-
-\Syntax {
-\Tex {\pdfpageref} \Something{page number} \Whatever{expandable}
-}
-
-\Syntax {
-\Tex {\pdfxformname} \Something{object number} \Whatever{expandable}
-}
-
-\Syntax {
-\Tex {\pdffontname} \Something{font} \Whatever{expandable}
-}
-
-\Syntax {
-\Tex {\pdffontobjnum} \Something{font} \Whatever{expandable}
-}
-
-\Syntax {
-\Tex {\pdffontsize} \Something{font} \Whatever{expandable}
-}
-
-\Syntax {
-\Tex {\pdfincludechars} \Something{font} \Something{general text} \Whatever{expandable}
-}
-
-\Syntax {
-\Tex {\leftmarginkern} \Something{box number} \Whatever{expandable}
-}
-
-\Syntax {
-\Tex {\rightmarginkern} \Something{box number} \Whatever{expandable}
-}
-
-\Syntax {
-\Tex {\pdfescapestring} \Something{general text} \Whatever{expandable}
-}
-
-\Syntax {
-\Tex {\pdfescapename} \Something{general text} \Whatever{expandable}
-}
-
-\Syntax {
-\Tex {\pdfescapehex} \Something{general text} \Whatever{expandable}
-}
-
-\Syntax {
-\Tex {\pdfunescapehex} \Something{general text} \Whatever{expandable}
-}
-
-\Syntax {
-\tex {ifpdfprimitive} \Something{control sequence} \Whatever{expandable}
-}
-
-\Syntax {
-\tex {ifincsname} \Whatever{expandable}
-}
-
-\Syntax {
-\Tex {\pdfstrcmp} \Something{general text} \Something{general text} \Whatever{expandable}
-}
-
-\Syntax {
-\Tex {\pdfmatch} \Optional{\Literal{icase}} \Optional{\Literal{subcount} \Something{number}}
- \Something{general text} \Something{general text} \Whatever{expandable}
-}
-
-\Syntax {
-\Tex {\pdflastmatch} \Something{integer} \Whatever{expandable}
-}
-
-\Syntax {
-\Tex {\ifpdfabsnum} \Whatever{expandable}
-}
-
-\Syntax {
-\Tex {\ifpdfabsdim} \Whatever{expandable}
-}
-
-\Syntax {
-\Tex {\pdfuniformdeviate} \Something{number} \Whatever{expandable}
-}
-
-\Syntax {
-\Tex {\pdfnormaldeviate} \Whatever{expandable}
-}
-
-\Syntax {
-\Tex {\pdfmdfivesum} \Optional{\Literal{file}} \Something{general text} \Whatever{expandable}
-}
-
-\Syntax {
-\Tex {\pdffilemoddate} \Something{general text} \Whatever{expandable}
-}
-
-\Syntax {
-\Tex {\pdffilesize} \Something{general text} \Whatever{expandable}
-}
-
-\Syntax {
-\Tex {\pdffiledump} \Optional{\Literal{offset} \Something{number}} \Optional{\Literal{length} \Something{number}} \Something{general text}
-\Whatever{expandable}
-}
-
-\Syntax {
-\Tex {\pdfcolorstackinit} \Optional{\Literal{page}} \Optional{\Literal{direct}} \Something{general text}
-\Whatever{expandable}
-}
-
-\Syntax {
-\Tex{\pdfinsetht} \Something{integer} \Whatever{expandable}
-}
-
-\Syntax {
-\Tex {\pdfximagebbox} \Something{integer} \Something{integer} \Whatever{expandable}
-}
-
-\stoppacked
-
-%%S NL
-%%S read-only integers:
-
-\subsubject{Read||only integers}
-
-\startpacked
-
-\Syntax {
-\Tex {\pdftexversion} \Whatever{read||only integer}
-}
-
-\Syntax {
-\Tex {\pdflastobj} \Whatever{read||only integer}
-}
-
-\Syntax {
-\Tex {\pdflastxform} \Whatever{read||only integer}
-}
-
-\Syntax {
-\Tex {\pdflastximage} \Whatever{read||only integer}
-}
-
-\Syntax {
-\Tex {\pdflastximagecolordepth} \Whatever{read||only integer}
-}
-
-\Syntax {
-\Tex {\pdflastximagepages} \Whatever{read||only integer}
-}
-
-\Syntax {
-\Tex {\pdflastannot} \Whatever{read||only integer}
-}
-
-\Syntax {
-\Tex {\pdflastlink} \Whatever{read||only integer}
-}
-
-\Syntax {
-\Tex {\pdflastxpos} \Whatever{read||only integer}
-}
-
-\Syntax {
-\Tex {\pdflastypos} \Whatever{read||only integer}
-}
-
-\Syntax {
-\Tex {\pdflastdemerits} \Whatever{read||only integer}
-}
-
-\Syntax {
-\Tex {\pdfelapsedtime} \Whatever{read||only integer}
-}
-
-\Syntax {
-\Tex {\pdfrandomseed} \Whatever{read||only integer}
-}
-
-\Syntax {
-\Tex {\pdfretval} \Whatever{read||only integer}
-}
-
-\Syntax {
-\Tex {\pdfshellescape} \Whatever{read||only integer}
-}
-
-% No longer available
-%\Syntax {
-%\Tex {\pdflastvbreakpenalty} \Whatever{read||only integer}
-%}
-
-\stoppacked
-
-%%S NL
-%%S general commands:
-
-\subsubject{General commands}
-
-\startpacked
-
-\Syntax {
-\Tex {\pdfobj} \Something{object type spec} \Whatever{h, v, m}
-}
-
-\Syntax {
-\Tex {\pdfrefobj} \Something{object number} \Whatever{h, v, m}
-}
-
-\Syntax {
-\Tex {\pdfxform} \Optional{\Something{xform attr spec}} \Something{box number} \Whatever{h, v, m}
-}
-
-\Syntax {
-\Tex {\pdfrefxform} \Something{object number} \Whatever{h, v, m}
-}
-
-\Syntax {
-\Tex {\pdfximage} \Optional{\Something{image attr spec}} %
- \Something{general text} \Whatever{h, v, m}
-}
-
-\Syntax {
-\Tex {\pdfrefximage} \Something{object number} \Whatever{h, v, m}
-}
-
-\Syntax {
-\Tex {\pdfannot} \Something{annot type spec} \Whatever{h, v, m}
-}
-
-\Syntax {
-\Tex {\pdfstartlink} %
- \Optional{\Something{rule spec}} %
- \Optional{\Something{attr spec}} \Something{action spec} \Whatever{h, m}
-}
-
-\Syntax {
-\Tex {\pdfendlink} \Whatever{h, m}
-}
-
-\Syntax {
-\Tex {\pdfoutline} \Something{outline spec} \Whatever{h, v, m}
-}
-
-\Syntax {
-\Tex {\pdfdest} \Something{dest spec} \Whatever{h, v, m}
-}
-
-\Syntax {
-\Tex {\pdfthread} \Something{thread spec} \Whatever{h, v, m}
-}
-
-\Syntax {
-\Tex {\pdfstartthread} \Something{thread spec} \Whatever{v, m}
-}
-
-\Syntax {
-\Tex {\pdfendthread} \Whatever{v, m}
-}
-
-\Syntax {
-\Tex {\pdfsavepos} \Whatever{h, v, m}
-}
-
-\Syntax {
-\Tex {\pdfinfo} \Something{general text}
-}
-
-\Syntax {
-\Tex {\pdfcatalog} \Something{general text} %
- \Optional{\Something{open-action spec}}
-}
-
-\Syntax {
-\Tex {\pdfnames} \Something{general text}
-}
-
-\Syntax {
-\Tex {\pdfmapfile} \Something{map spec}
-}
-
-\Syntax {
-\Tex {\pdfmapline} \Something{map spec}
-}
-
-\Syntax {
-\Tex {\pdffontattr} \Something{font} \Something{general text}
-}
-
-\Syntax {
-\Tex {\pdftrailer} \Something{general text}
-}
-
-\Syntax {
-\Tex {\pdffontexpand} \Something{font} \Something{expand spec}
-}
-
-\Syntax {
-\Tex {\letterspacefont} \Something{control sequence} \Something{font} \Something{integer}
-}
-
-\Syntax {
-\Tex {\pdfcopyfont} \Something{control sequence} \Something{font}
-}
-
-\Syntax {
-\Tex {\pdfglyphtounicode} \Something{general text} \Something{general text}
-}
-
-\Syntax {
-\Tex {\vadjust} \Optional{\Something{pre spec}} \Something{filler} \Lbrace \Something{vertical mode material} \Rbrace \Whatever{h, m}
-}
-
-\Syntax {
-\Tex {\quitvmode}
-}
-
-\Syntax {
-\Tex {\pdfliteral} \Optional{\Something {pdfliteral spec}} \Something{general text} \Whatever{h, v, m}
-}
-
-\Syntax {
-\Tex {\special} \Something{pdfspecial spec}
-}
-
-\Syntax {
-\Tex {\pdfresettimer}
-}
-
-\Syntax {
-\Tex {\pdfsetrandomseed} \Something{number}
-}
-
-\Syntax {
-\Tex {\pdfnoligatures} \Something{font}
-}
-
-\Syntax {
-\Tex {\pdfprimitive} \Something{control sequence}
-}
-
-\Syntax {
-\Tex {\pdfcolorstack} \Something{stack number} \Something{stack action} \Something{general text}
-}
-
-\Syntax {
-\Tex {\pdfsetmatrix}
-}
-
-\Syntax {
-\Tex {\pdfsave}
-}
-
-\Syntax {
-\Tex {\pdfrestore}
-}
-\stoppacked
+% Generated list of primitives (see Makefile).
+\input pdftex-syntax.tex
\subsubject{General definitions and syntax rules}
\startpacked
%%S NL
-%%S syntax rules:
+%%S Syntax rules:
-\Syntax {
+\Syntax{
\Something{general text} \Means %
\Lbrace \Something{balanced text} \Rbrace
}
-\Syntax {
+\Syntax{
\Something{attr spec} \Means %
- \Literal {attr} \Something{general text}
+ \Literal{attr} \Something{general text}
}
-\Syntax {
+\Syntax{
\Something{resources spec} \Means %
- \Literal {resources} \Something{general text}
+ \Literal{resources} \Something{general text}
}
-\Syntax {
+\Syntax{
\Something{rule spec} \Means %
- (\Literal {width} \Or \Literal {height} \Or \Literal {depth}) %
- \Something{dimension} \Optional{\Something{rule spec}}
+ (\Literal{width} \Or \Literal{height} \Or \Literal{depth}) %
+ \Something{dimen} \Optional{\Something{rule spec}}
}
-%\Syntax {\Something{object type spec} \Means
-% \Optional{\Literal {stream}
+%\Syntax{\Something{object type spec} \Means
+% \Optional{\Literal{stream}
% \Optional{\Something{attr spec}}} \Something{object contents}}
-\Syntax {
+\Syntax{
\Something{object type spec} \Means %
\Literal{reserveobjnum}
\Or \Next %
@@ -2485,7 +1859,7 @@ new Didot (1\,nd~=~0.375\,mm) and the new Cicero (1\,nc~=~12\,nd)
\Something{object contents}
}
-\Syntax {
+\Syntax{
\Something{annot type spec} \Means %
\Literal{reserveobjnum}
\Or \Next %
@@ -2494,18 +1868,18 @@ new Didot (1\,nd~=~0.375\,mm) and the new Cicero (1\,nc~=~12\,nd)
\Something{general text}
}
-\Syntax {
+\Syntax{
\Something{object contents} \Means %
\Something{file spec}
\Or \Something{general text}
}
-\Syntax {
+\Syntax{
\Something{xform attr spec} \Means %
\Optional{\Something{attr spec}} \Optional{\Something{resources spec}}
}
-\Syntax {
+\Syntax{
\Something{image attr spec} \Means %
\Optional{\Something{rule spec}} %
\Optional{\Something{attr spec}} %
@@ -2514,7 +1888,7 @@ new Didot (1\,nd~=~0.375\,mm) and the new Cicero (1\,nc~=~12\,nd)
\Optional{\Something{pdf box spec}}
}
-\Syntax {
+\Syntax{
\Something{outline spec} \Means %
\Optional{\Something{attr spec}} %
\Something{action spec} %
@@ -2522,20 +1896,20 @@ new Didot (1\,nd~=~0.375\,mm) and the new Cicero (1\,nc~=~12\,nd)
\Something{general text}
}
-\Syntax {
+\Syntax{
\Something{action spec} \Means %
- \Literal {user} \Something{user-action spec}
- \Or \Literal {goto} \Something{goto-action spec}
- \Or \Next \Literal {thread} \Something{thread-action spec}
+ \Literal{user} \Something{user-action spec}
+ \Or \Literal{goto} \Something{goto-action spec}
+ \Or \Next \Literal{thread} \Something{thread-action spec}
}
-\Syntax {
+\Syntax{
\Something{user-action spec} \Means %
\Something{general text}
}
%HE Check:
-\Syntax {
+\Syntax{
\Something{goto-action spec} \Means %
\Something{numid}
\Or \Next \Optional{\Something{file spec}} \Something{nameid}
@@ -2544,20 +1918,20 @@ new Didot (1\,nd~=~0.375\,mm) and the new Cicero (1\,nc~=~12\,nd)
\Or \Next \Something{file spec} \Optional{\Something{page spec}} \Something{general text} \Something{newwindow spec}
}
-\Syntax {
+\Syntax{
\Something{thread-action spec} \Means %
\Optional{\Something{file spec}} \Something{numid}
\Or \Optional{\Something{file spec}} \Something{nameid}
}
-\Syntax {
+\Syntax{
\Something{open-action spec} \Means %
- \Literal {openaction} \Something{action spec}
+ \Literal{openaction} \Something{action spec}
}
-\Syntax {
+\Syntax{
\Something{colorspace spec} \Means %
- \Literal {colorspace} \Something{number}
+ \Literal{colorspace} \Something{number}
}
\Syntax{
@@ -2580,62 +1954,62 @@ new Didot (1\,nd~=~0.375\,mm) and the new Cicero (1\,nc~=~12\,nd)
\Literal{+} \Or \Literal{=} \Or \Literal{-}
}
-\Syntax {
+\Syntax{
\Something{numid} \Means %
- \Literal {num} \Something{number}
+ \Literal{num} \Something{number}
}
-\Syntax {
+\Syntax{
\Something{nameid} \Means %
- \Literal {name} \Something{general text}
+ \Literal{name} \Something{general text}
}
-\Syntax {
+\Syntax{
\Something{newwindow spec} \Means %
- \Literal {newwindow} \Or \Literal {nonewwindow}
+ \Literal{newwindow} \Or \Literal{nonewwindow}
}
-\Syntax {
+\Syntax{
\Something{dest spec} \Means %
\Something{numid} \Something{dest type}
\Or \Something{nameid} \Something{dest type}
}
-\Syntax {
+\Syntax{
\Something{dest type} \Means %
- \Literal {xyz} \Optional{\Literal {zoom} \Something{number}}
- \Or \Literal {fitr} \Something{rule spec}
- \Or \Next \Literal {fitbh}
- \Or \Literal {fitbv}
- \Or \Literal {fitb}
- \Or \Literal {fith}
- \Or \Literal {fitv}
- \Or \Literal {fit}
+ \Literal{xyz} \Optional{\Literal{zoom} \Something{number}}
+ \Or \Literal{fitr} \Something{rule spec}
+ \Or \Next \Literal{fitbh}
+ \Or \Literal{fitbv}
+ \Or \Literal{fitb}
+ \Or \Literal{fith}
+ \Or \Literal{fitv}
+ \Or \Literal{fit}
}
-\Syntax {
+\Syntax{
\Something{thread spec} \Means %
\Optional{\Something{rule spec}} %
\Optional{\Something{attr spec}} %
\Something{id spec}
}
-\Syntax {
+\Syntax{
\Something{id spec} \Means %
\Something{numid} \Or \Something{nameid}
}
-\Syntax {
+\Syntax{
\Something{file spec} \Means %
- \Literal {file} \Something{general text}
+ \Literal{file} \Something{general text}
}
-\Syntax {
+\Syntax{
\Something{page spec} \Means %
- \Literal {page} \Something{number}
+ \Literal{page} \Something{number}
}
-\Syntax {
+\Syntax{
\Something{expand spec} \Means %
\Something{stretch} %
\Something{shrink} %
@@ -2643,74 +2017,74 @@ new Didot (1\,nd~=~0.375\,mm) and the new Cicero (1\,nc~=~12\,nd)
\Optional{\Literal{autoexpand}}
}
-\Syntax {
+\Syntax{
\Something{stretch} \Means %
\Something{number}
}
-\Syntax {
+\Syntax{
\Something{shrink} \Means %
\Something{number}
}
-\Syntax {
+\Syntax{
\Something{step} \Means %
\Something{number}
}
-\Syntax {
+\Syntax{
\Something{pre spec} \Means %
\Literal{pre}
}
-\Syntax {
+\Syntax{
\Something{pdfliteral spec} \Means %
\Literal{direct} \Or \Literal{page}
}
-\Syntax {
+\Syntax{
\Something{pdfspecial spec} \Means %
- \Lbrace \Optional{\Something{pdfspecial id} \Optional{\Something{pdfspecial modifier}}} %
+ \Lbrace \Optional{\Something{pdfspecial id} %
+ \Optional{\Something{pdfspecial modifier}}} %
\Something{balanced text} \Rbrace
}
-\Syntax {
+\Syntax{
\Something{pdfspecial id} \Means %
\Literal{pdf:} \Or \Literal{PDF:}
}
-\Syntax {
+\Syntax{
\Something{pdfspecial modifier} \Means %
\Literal{direct:}
}
-\Syntax {
+\Syntax{
\Something{stack action} \Means %
\Literal{set} \Or \Literal{push} \Or \Literal{pop} \Or \Literal{current}
}
\stoppacked
-A \Something {general text} is expanded immediately, like \type{\special}
+A \Something{general text} is expanded immediately, like \type{\special}
in traditional \TEX, unless explicitly mentioned otherwise.
Some of the object and image related primitives can be prefixed by
-\type {\immediate}. More about that in the next sections.
+\type{\immediate}. More about that in the next sections.
%***********************************************************************
\section[primitives]{\PDFTEX\ primitives}
-Here follows a short description of the primitives added by \PDFTEX\
-to the original \TEX\ engine (other extensions by \MLTEX\ and \ENCTEX\
-are not listed). One way to learn more about how to use these new
-primitives is to have a look at the file \filename {samplepdf.tex} in the
-\PDFTEX\ distribution.
+Here follows a description of the primitives added by \PDFTEX\ to the
+original \TEX\ engine (other extensions by \ETEX, \MLTEX\ and \ENCTEX\
+are not listed). Many of these primitives are described further in the
+\filename {samplepdf.tex} file in the \PDFTEX\ distribution.
-Note that if the output is \DVI\ then the \PDFTEX\ specific dimension
-parameters are not used at all. However some \PDFTEX\ integer parameters
-can affect the \DVI\ as well as \PDF\ output (currently \type{\pdfoutput}
-and \type{\pdfadjustspacing}).
+If the output is \DVI, then the \PDFTEX-specific dimension parameters
+are not used at all. However, some \PDFTEX\ integer parameters can
+affect \DVI\ as well as \PDF\ output (specifically, \type{\pdfoutput} and
+\type{\pdfadjustspacing}).
%A warning to macro writers: The \PDFTEX-team reserves the namespaces
%\type{\pdf*} and \type{\ptex*} for use by \PDFTEX; if you define macros
@@ -2732,8 +2106,7 @@ situation.
\subsection{Document setup}
-\pdftexprimitive {\Syntax {\Tex {\pdfoutput} \Whatever{integer}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfoutput} \Whatever{integer}}}
\bookmark{\tex{pdfoutput}}
This parameter specifies whether the output format should be \DVI\ or
@@ -2761,8 +2134,7 @@ engine is used in distributions also for non-\PDF\ formats (\eg\
\LATEX), so \type{\pdfoutput} may be defined even when the output format
is \DVI.
-\pdftexprimitive {\Syntax {\Tex {\pdfminorversion} \Whatever{integer}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfminorversion} \Whatever{integer}}}
\bookmark{\tex{pdfminorversion}}
This primitive sets the \PDF\ version of the generated file and the
@@ -2783,8 +2155,7 @@ This was originally a shortened synonym of the
\introduced{1.30.0}
-\pdftexprimitive {\Syntax {\Tex {\pdfcompresslevel} \Whatever{integer}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfcompresslevel} \Whatever{integer}}}
\bookmark{\tex{pdfcompresslevel}}
This integer parameter specifies the level of {\em stream} compression
@@ -2796,8 +2167,7 @@ range will be adjusted to the nearest meaningful value. This parameter
is read each time \PDFTEX\ starts a stream. Setting
\type{\pdfcompresslevel=0} is useful for \PDF\ stream debugging.
-\pdftexprimitive {\Syntax {\Tex {\pdfobjcompresslevel} \Whatever{integer}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfobjcompresslevel} \Whatever{integer}}}
\bookmark{\tex{pdfobjcompresslevel}}
This integer parameter controls the compression of {\em non-stream}
@@ -2812,7 +2182,7 @@ and links are used.
\introduced{1.40.0}
The writing of compressed objects is enabled by setting
-\type{\pdfobjcompresslevel} to a value between 1 and~3; it's
+\type{\pdfobjcompresslevel} to a value between~1 and~3; it's
disabled by value~0 (default). Enabling requires that also
\type{\pdfminorversion}~$>$~4. If \type{\pdfobjcompresslevel}~$>$~0,
but \type{\pdfminorversion}~$<$~5, a warning is given and object stream
@@ -2842,8 +2212,7 @@ compatibility, but this is currently not implemented, as \PDF-1.5 was
rather quickly adopted by modern \PDF\ viewers. Also not implemented is
the optional \type{/Extends} key.
-\pdftexprimitive {\Syntax {\Tex {\pdfdecimaldigits} \Whatever{integer}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfdecimaldigits} \Whatever{integer}}}
\bookmark{\tex{pdfdecimaldigits}}
This integer parameter specifies the numeric accuracy of real
@@ -2861,8 +2230,7 @@ the \PDF\ output.
When including huge \METAPOST\ images using \filename {supp-pdf.tex}, one can
limit the accuracy to two digits by typing: \type{\twodigitMPoutput}.
-\pdftexprimitive {\Syntax {\Tex {\pdfhorigin} \Whatever{dimension}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfhorigin} \Whatever{dimen}}}
\bookmark{\tex{pdfhorigin}}
This parameter can be used to set the horizontal offset the output box
@@ -2880,8 +2248,7 @@ command. Or, you can preadjust the \type{\pdfhorigin} value before typing
\type{\mag}, so that its value after the \type{\mag} command ends up at
1~true inch again.
-\pdftexprimitive {\Syntax {\Tex {\pdfvorigin} \Whatever{dimension}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfvorigin} \Whatever{dimen}}}
\bookmark{\tex{pdfvorigin}}
This parameter is the vertical companion of \type{\pdfhorigin}, and the
@@ -2890,8 +2257,7 @@ in mind that the \TEX\ coordinate system starts in the top left corner
(downward), while \PDF\ coordinates start at the bottom left corner
(upward).
-\pdftexprimitive {\Syntax {\Tex {\pdfpagewidth} \Whatever{dimension}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfpagewidth} \Whatever{dimen}}}
\bookmark{\tex{pdfpagewidth}}
This dimension parameter specifies the page width of the \PDF\ output
@@ -2905,8 +2271,7 @@ $w_{\hbox{\txx box being shipped out}} + 2 \times (\hbox{horigin} +
\hbox{\type{\hoffset}})$. When part of the page falls off the paper or
screen, you can be rather sure that this parameter is set wrong.
-\pdftexprimitive {\Syntax {\Tex {\pdfpageheight} \Whatever{dimension}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfpageheight} \Whatever{dimen}}}
\bookmark{\tex{pdfpageheight}}
Similar to the previous item, this dimension parameter specifies the
@@ -2917,54 +2282,100 @@ the wished true page height.
%***********************************************************************
-\subsection{The document info and catalog}
-
-\pdftexprimitive {\Syntax {\Tex {\pdfinfo} \Something{general text}}}
+\subsection[sec.docinfocatalog]{The document info and catalog}
+\pdftexprimitive{\Syntax{\Tex{\pdfinfo} \Something{general text}}}
\bookmark{\tex{pdfinfo}}
-This primitive allows the user to add information to the document info
-section; if this information is provided, it can be extracted, \eg\ by the
-pdfinfo program, or by the Adobe Reader (version 7.0: menu option {\em File
-$\longrightarrow$ Document Properties}). The \Something{general text} is
-a collection of key||value||pairs. The key names are preceded by a \type{/},
-and the values, being strings, are given between parentheses. All keys
-are optional. Possible keys are \type{/Author}, \type{/CreationDate}
-(defaults to current date including time zone info), \type{/ModDate},
-\type{/Creator} (defaults to \type {TeX}), \type{/Producer} (defaults
-to \hbox{\tt pdfTeX-\currentpdftex}), \type{/Title}, \type{/Subject},
-and \type{/Keywords}.
+This primitive allows the user to specify information for the document
+info dictionary; if this information is provided, it can be extracted,
+\eg\ by the \type{pdfinfo} program. The \Something{general text} is a
+collection of key||value||pairs. The key names are preceded by a
+\type{/}, and the values, being strings, are given between
+parentheses. All keys, and the primitive itself, are optional. Possible
+keys are:\crlf
+\type{/Title},\crlf
+\type{/Author},\crlf
+\type{/Subject},\crlf
+\type{/Keywords},\crlf
+\type{/Producer} (defaults to \hbox{\tt pdfTeX-\currentpdftex}),\crlf
+\type{/Creator} (defaults to \type{TeX}),\crlf
+\type{/CreationDate} (defaults to current date and time, with time zone),\crlf
+\type{/ModDate} (same default),\crlf
+\type{/Trapped} (defaults to \type{/False},\crlf
+\type{/PTEX.Fullbanner} (defaults to the \type{\pdftexbanner} string, q.v.).
\type{/CreationDate} and \type{/ModDate} are expressed in the form
-\type{D:YYYYMMDDhhmmssTZ..}, where \type{YYYY} is the year, \type{MM} is
+\type{D:YYYYMMDDhhmmssTZ}, where \type{YYYY} is the year, \type{MM} is
the month, \type{DD} is the day, hh is the hour, \type{mm} is the
-minutes, \type{ss} is the seconds, and \type{TZ..} is an optional string
-denoting the time zone. An example of this format is shown below. For
-details please refer to the \PDFReference.
+minutes, \type{ss} is the seconds, and \type{TZ} is an optional string
+denoting the time zone. For example, this is the Unix epoch, the
+beginning of 1970-01-01 UTC, in this format: \type{19700101000000Z}
-Multiple appearances of \type{\pdfinfo} will be concatenated. In
-general, if a key is given more than once, one may expect that the first
-appearance will be used. Be aware however, that this behaviour is
-viewer dependent. Except expansion, \PDFTEX\ does not perform any
-further operations on \Something{general text} provided by the user.
+Multiple appearances of \type{\pdfinfo} are concatenated. Usually if a
+key is given more than once, the first appearance will be used, but this
+is viewer||dependent. Except for standard \TeX\ expansion, \PDFTEX\ does
+not perform any further operations on \Something{general text} provided
+by the user.
-An example of the use of \type{\pdfinfo} is:
+Here is an example of using \type{\pdfinfo} to include the
+information not supplied by \PDFTEX:
\startesctyping
\pdfinfo {
/Title (example.pdf)
- /Creator (TeX)
- /Producer (pdfTeX @currentpdftex)
/Author (Tom and Jerry)
- /CreationDate (D:20061226154343+01'00')
- /ModDate (D:20061226155343+01'00')
/Subject (Example)
- /Keywords (mouse, cat) }
+ /Keywords (mouse, cat)
+}
\stopesctyping
-\pdftexprimitive {\Syntax {\Tex {\pdfcatalog} \Something{general text}
-\Optional{\Something{open-action spec}}}}
+For more details on all this, see the \PDFReference.
+
+\pdftexprimitive{\Syntax{\Tex{\pdfinfoomitdate} \Whatever{integer}}}
+\bookmark{\tex{pdfinfoomitdate}}
+If nonzero, omit the \type{/CreationDate} and \type{/ModDate} keys from
+the document info dictionary described above. This can be useful in
+making reproducible \PDF{}s. \introduced{1.40.17}
+
+\pdftexprimitive{\Syntax{\Tex{\pdfsuppressptexinfo} \Whatever{integer}}}
+\bookmark{\tex{pdfsuppressptexinfo}}
+
+Treated as a bitmask, specifying which \type{PTEX.} keys to omit from
+the output:
+
+\startbuffer
+\starttabulate[|l|l|]
+\HL
+\NC \bf value \NC \bf suppresses \NC\NR
+\HL
+\NC \tt 1 \NC \type{PTEX.Fullbanner} \NC\NR
+\NC \tt 2 \NC \type{PTEX.FileName} \NC\NR
+\NC \tt 4 \NC \type{PTEX.PageNumber} \NC\NR
+\NC \tt 8 \NC \type{PTEX.InfoDict} \NC\NR
+\HL
+\stoptabulate
+\stopbuffer
+
+\placetable
+ [here][pagemode]
+ {\type{\pdfsuppressptexinfo} bit meanings.}
+ {\getbuffer}
+
+Thus, the value \type{-1}, or the sum of all defined bits, will suppress
+everything.
+
+\type{PTEX.Fullbanner} is included by default in the general document
+info dictionary, as mentioned under \type{\pdfinfo} above. The other
+\type{PTEX.*} keys are included when a \PDF\ is included in the document
+(and not otherwise), as described in \in{section}[sec.addpdfkeys]
+
+This conditional suppression can be useful in making reproducible
+\PDF{}s. \introduced{1.40.17}
+
+\pdftexprimitive{\Syntax{\Tex{\pdfcatalog} \Something{general text}
+ \Optional{\Something{open-action spec}}}}
\bookmark{\tex{pdfcatalog}}
Similar to the document info section is the document catalog, where keys
@@ -2999,8 +2410,7 @@ document and is specified in the same way as internal links, see \in
{section} [linking]. Instead of using this method, one can also write the
open action directly into the catalog.
-\pdftexprimitive {\Syntax {\Tex {\pdfnames} \Something{general text}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfnames} \Something{general text}}}
\bookmark{\tex{pdfnames}}
This primitive inserts the \Something{general text} to the \type
@@ -3008,19 +2418,26 @@ This primitive inserts the \Something{general text} to the \type
conform to the specifications as laid down in the \PDFReference,
otherwise the document can be invalid.
-\pdftexprimitive {\Syntax {\Tex {\pdftrailer} \Something{general text}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdftrailer} \Something{general text}}}
\bookmark{\tex{pdftrailer}}
This command puts its argument text verbatim into the file trailer
dictionary. \introduced{1.11a}
+\pdftexprimitive{\Syntax{\Tex{\pdftrailerid} \Something{general text}}}
+\bookmark{\tex{pdftrailerid}}
+
+Use the \Something{general text} to seed the \type{/ID} value in the
+trailer, instead of the default combination of the absolute input file
+name and starting time. If the argument is empty, the \type{/ID} is
+omitted entirely. This can be useful in making reproducible
+\PDF{}s. \introduced{1.40.17}
+
%***********************************************************************
\subsection{Fonts}
-\pdftexprimitive {\Syntax {\Tex {\pdfpkresolution} \Whatever{integer}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfpkresolution} \Whatever{integer}}}
\bookmark{\tex{pdfpkresolution}}
This integer parameter specifies the default resolution of embedded \PK\
@@ -3028,13 +2445,12 @@ fonts and is read when \PDFTEX\ embeds a \PK\ font during finishing the
\PDF\ output. As bitmap fonts are still rendered poorly by some \PDF\
viewers, it is best to use Type~1 fonts when available.
-\pdftexprimitive {\Syntax {\Tex {\pdffontexpand}
-\Something{font} \Something{stretch} \Something{shrink}
-\Something{step} \Optional{\Literal{autoexpand}}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdffontexpand}
+ \Something{font} \Something{stretch} \Something{shrink}
+ \Something{step} \Optional{\Literal{autoexpand}}}}
\bookmark{\tex{pdffontexpand}}
-This extension to \TEX's font definitions controls a \PDFTEX\ automatism
+This extension to \TEX's font definitions controls a major \PDFTEX\ feature
called {\em font expansion}. We describe this by an example:
\starttyping
@@ -3059,7 +2475,7 @@ gaps is acceptable. This glyph stretching and shrinking is called
There are two different modes for font expansion:
-First, if the \type{autoexpand} option is there --- which is the
+First, if the \type{autoexpand} option is given --- which is the
recommended mode --- only a single map entry is needed for all expanded
font versions, using the name of the unexpanded \TFM\ file ({\em
tfmname}). No expanded {\em tfmname} versions need to mentioned (they are
@@ -3077,7 +2493,7 @@ expansion gets more tedious, as there must be map entries for \TFM\ files
in all required expansion values. The expanded {\em tfmname} variants
are constructed by adding the font expansion value to the {\em tfmname}
of the base font, \eg\ there must be a map entry with {\em tfmname}
-\type{sometfm+10} for 1\,\% stretch or \type {sometfm-15} for 1.5\,\%
+\type{sometfm+10} for 1\,\% stretch or \type{sometfm-15} for 1.5\,\%
shrink. This also means, that for each expanded font variant a \TFM\
file with properly expanded metrics must exist. Having several map
entries for the various expansion values of a font requires to provide
@@ -3107,8 +2523,7 @@ vertical part of the glyph becomes thicker, and looks incompatible with
an unscaled original. With a Multiple Master situation, one can stretch
while keeping this thickness compatible.
-\pdftexprimitive {\Syntax {\Tex {\pdfadjustspacing} \Whatever{integer}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfadjustspacing} \Whatever{integer}}}
\bookmark{\tex{pdfadjustspacing}}
This primitive provides a switch for enabling font expansion. By default,
@@ -3132,11 +2547,11 @@ related to the \Something{stretch} and \Something{shrink} settings
for the \type{\pdffontexpand} primitive, unless this is given with the
\type{autoexpand} option.
-\pdftexprimitive {\Syntax {\Tex {\efcode} \Something{font} \Something{8-bit number} \Whatever{integer}}}
-
+\pdftexprimitive{\Syntax{\Tex{\efcode} \Something{font}
+ \Something{8-bit number} \Whatever{integer}}}
\bookmark{\tex{efcode}}
-We didn't yet tell the whole story. One can imagine that some glyphs are
+We haven't yet told the whole story. One can imagine that some glyphs are
visually more sensitive to stretching or shrinking than others. Then the
\type{\efcode} primitive can be used to influence the expandability of
individual glyphs within a given font, as a factor to the expansion
@@ -3157,8 +2572,7 @@ expansion is still bound to the steps as defined by \type{\pdffontexpand}
primitive, otherwise one would end up with more possible font inclusions
than would be comfortable.
-\pdftexprimitive {\Syntax {\Tex {\pdfprotrudechars} \Whatever{integer}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfprotrudechars} \Whatever{integer}}}
\bookmark{\tex{pdfprotrudechars}}
Yet another way of optimizing paragraph breaking is to let certain
@@ -3175,13 +2589,13 @@ If you want to protrude some item other than a character (\eg\
a \type{\hbox}), you can do so by padding the item with an invisible
zero||width character, for which protrusion is activated.
-\pdftexprimitive {\Syntax {\Tex {\rpcode} \Something{font} \Something{8-bit number} \Whatever{integer}}}
-
+\pdftexprimitive{\Syntax{\Tex{\rpcode} \Something{font}
+ \Something{8-bit number} \Whatever{integer}}}
\bookmark{\tex{rpcode}}
The amount that a character from a given font may shift into the right
-margin (`character protrusion') is set by the primitive \type {\rpcode}.
-The protrusion distance is the integer value given to \type {\rpcode},
+margin (`character protrusion') is set by the primitive \type{\rpcode}.
+The protrusion distance is the integer value given to \type{\rpcode},
multiplied with 0.001\,em from the current font. The given integer value
is clipped to the range $-1000..1000$, corresponding to a usable
protrusion range of $-$1\,em..1\,em. Example:
@@ -3199,17 +2613,16 @@ Remark: old versions of \PDFTEX\ use the character width as measure. This
was changed to a proportion of the em-width after \THANH\ finished his
master's thesis.
-\pdftexprimitive {\Syntax {\Tex {\lpcode} \Something{font} \Something{8-bit number}
-\Whatever{integer}}}
-
+\pdftexprimitive{\Syntax{\Tex{\lpcode} \Something{font}
+ \Something{8-bit number} \Whatever{integer}}}
\bookmark{\tex{lpcode}}
This is similar to \type{\rpcode}, but affects the amount by which
characters may protrude into the left margin. Also here the given integer
value is clipped to the range $-1000..1000$.
-\pdftexprimitive {\Syntax {\Tex {\leftmarginkern} \Something{box number} \Whatever{expandable}}}
-
+\pdftexprimitive{\Syntax{\Tex{\leftmarginkern} \Something{box number}
+ \Whatever{expandable}}}
\bookmark{\tex{leftmarginkern}}
The \Tex{\leftmarginkern} \Something{box number} primitive expands to the
@@ -3243,8 +2656,8 @@ proper margin kerning (which is then done by ordinary kerns).
\hbox to\hsize{\kern\dimen0\unhcopy\testline\kern\dimen1}
\stoptyping
-\pdftexprimitive {\Syntax {\Tex {\rightmarginkern} \Something{box number} \Whatever{expandable}}}
-
+\pdftexprimitive{\Syntax{\Tex{\rightmarginkern} \Something{box number}
+ \Whatever{expandable}}}
\bookmark{\tex{rightmarginkern}}
The \Tex{\rightmarginkern} \Something{box number} primitive expands to
@@ -3253,8 +2666,8 @@ stored in \Tex{\box} \Something{box number}. See \type{\leftmarginkern}
for more details.
\introduced{1.30.0}
-\pdftexprimitive {\Syntax {\Tex {\letterspacefont} \Something{control sequence} \Something{font} \Something{integer}}}
-
+\pdftexprimitive{\Syntax{\Tex{\letterspacefont} \Something{control sequence}
+ \Something{font} \Something{integer}}}
\bookmark{\tex{letterspacefont}}
This primitive creates an instance of \Something{font} with the widths
@@ -3274,25 +2687,24 @@ Negative values are allowed for \Something{integer}.
Letter spacing works natively in \PDF\ mode only, unless special fonts are
devised (in our example, a \type{myfont+100ls} font), as with font expansion.
-\pdftexprimitive {\Syntax {\Tex {\pdfcopyfont} \Something{control sequence} \Something{font}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfcopyfont} \Something{control sequence}
+ \Something{font}}}
\bookmark{\tex{pdfcopyfont}}
This primitive defines \Something{control sequence} as a synonym for
\Something{font}.
-\pdftexprimitive {\Syntax {\Tex {\pdffontattr} \Something{font} \Something{general text}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdffontattr} \Something{font}
+ \Something{general text}}}
\bookmark{\tex{pdffontattr}}
-This primitive inserts the \Something{general text} to the \type {/Font}
+This primitive inserts the \Something{general text} to the \type{/Font}
dictionary. The text must conform to the specifications as laid down in
the \PDFReference, otherwise the document can be invalid. For examples,
see the \type{cmap} and \type{CJK} packages.
-\pdftexprimitive {\Syntax {\Tex {\pdffontname} \Something{font} \Whatever
-{expandable}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdffontname} \Something{font}
+ \Whatever{expandable}}}
\bookmark{\tex{pdffontname}}
In \PDF\ files produced by \PDFTEX\ one can recognize a font resource
@@ -3306,9 +2718,8 @@ In the current implementation, when \type{\pdfuniqueresname} (see below)
is set to a positive value, the \type{\pdffontname} still returns only the
number from the font resource name, but not the appended random string.
-\pdftexprimitive {\Syntax {\Tex {\pdffontobjnum} \Something{font} \Whatever
-{expandable}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdffontobjnum} \Something{font}
+ \Whatever{expandable}}}
\bookmark{\tex{pdffontobjnum}}
This command is similar to \type{\pdffontname}, but it returns the
@@ -3317,21 +2728,19 @@ the font resource name. \Eg, if the font dictionary (\type{/Type
/Font}) in \PDF\ object~3 corresponds to some \TEX\ font \type{\foo},
the \type{\pdffontobjnum\foo} gives the number~\type{3}.
-Use of \type{\pdffontname} and \type {\pdffontobjnum} allows users full
+Use of \type{\pdffontname} and \type{\pdffontobjnum} allows users full
access to all the font resources used in the document.
-\pdftexprimitive {\Syntax {\Tex {\pdffontsize} \Something{font} \Whatever
-{expandable}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdffontsize} \Something{font}
+ \Whatever{expandable}}}
\bookmark{\tex{pdffontsize}}
This primitive expands to the font size of the given font, with unit
\type{pt}. \Eg, when using the plain \TeX\ macro package, the call
\type{\pdffontsize\tenrm} expands to \type{10.0pt}.
-\pdftexprimitive {\Syntax {\Tex {\pdfincludechars} \Something{font}
-\Something{general text}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfincludechars} \Something{font}
+ \Something{general text} \Whatever{expandable}}}
\bookmark{\tex{pdfincludechars}}
This command causes \PDFTEX\ to treat the characters in \Something{general
@@ -3339,16 +2748,14 @@ text} as if they were used with \Something{font}\unkern, which means that the
corresponding glyphs will be embedded into the font resources in the \PDF\
output. Nothing is appended to the list being built.
-\pdftexprimitive {\Syntax {\Tex {\pdfuniqueresname} \Whatever{integer}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfuniqueresname} \Whatever{integer}}}
\bookmark{\tex{pdfuniqueresname}}
When this primitive is assigned a positive number, \PDF\ resource names
will be made reasonably unique by appending a random string consisting
of six \ASCII\ characters.
-\pdftexprimitive {\Syntax {\Tex {\pdfmapfile} \Something{map spec}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfmapfile} \Something{map spec}}}
\bookmark{\tex{pdfmapfile}}
This primitive is used for reading a font map file consisting of
@@ -3439,8 +2846,7 @@ This would always read the file \type{myspecial.map} after the default
\type{pdftex.map} file.
-\pdftexprimitive {\Syntax {\Tex {\pdfmapline} \Something{map spec}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfmapline} \Something{map spec}}}
\bookmark{\tex{pdfmapline}}
Similar to \type{\pdfmapfile}, but here you can give a single
@@ -3461,9 +2867,7 @@ of the default map file, if it comes early enough in the \TeX\
input. \introduced{1.20a}
-\pdftexprimitive {\Syntax {\Tex {\pdfsuppresswarningdupmap}
-\Whatever{integer}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfsuppresswarningdupmap} \Whatever{integer}}}
\bookmark{\tex{pdfsuppresswarningdupmap}}
Ordinarily, \PDFTEX\ gives a warning when a duplicate map entry for a
@@ -3474,8 +2878,7 @@ be installed on the system. Then seeing the warnings on every run is
just noise, and can be suppressed by setting this parameter to a
positive number. \introduced{1.40.13}
-\pdftexprimitive {\Syntax {\Tex {\pdftracingfonts} \Whatever{integer}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdftracingfonts} \Whatever{integer}}}
\bookmark{\tex{pdftracingfonts}}
This integer parameter specifies the level of verbosity for info about
@@ -3498,8 +2901,7 @@ together with the font size, \eg:
Setting \type{\pdftracingfonts} to a value other than~0 or~1 is not
recommended, to allow future extensions. \introduced{1.30.0}
-\pdftexprimitive {\Syntax {\Tex {\pdfmovechars} \Whatever{integer}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfmovechars} \Whatever{integer}}}
\bookmark{\tex{pdfmovechars}}
Since \PDFTEX\ version 1.30.0 the primitive \type{\pdfmovechars} is obsolete,
@@ -3507,8 +2909,7 @@ and its use merely leads to a warning. (This primitive specified whether
\PDFTEX\ should try to move characters in range 0..31 to higher slots;
its sole purpose was to remedy certain bugs of early \PDF\ viewers.)
-\pdftexprimitive {\Syntax {\Tex {\pdfpkmode} \Whatever{tokens}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfpkmode} \Whatever{tokens}}}
\bookmark{\tex{pdfpkmode}}
The \type{\pdfpkmode} is a token register that sets the \METAFONT\ mode for
@@ -3516,15 +2917,14 @@ pixel font generation. The contents of this register is dumped into the
format, so one can (optionally) preset it \eg\ in \type{pdftexconfig.tex}.
\introduced{1.30.0}
-\pdftexprimitive {\Syntax {\Tex {\pdfnoligatures} \Something{font}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfnoligatures} \Something{font}}}
\bookmark{\tex{pdfnoligatures}}
This disables all ligatures in the loaded font \Something{font}.
\introduced{1.30.0}
-\pdftexprimitive {\Syntax {\Tex {\tagcode} \Something{font} \Something{character code} \Whatever{integer}}}
-
+\pdftexprimitive{\Syntax{\Tex{\tagcode} \Something{font}
+ \Something{character code} \Whatever{integer}}}
\bookmark{\tex{tagcode}}
This primitive accesses a character's \type{char_tag} info. It is meant
@@ -3542,7 +2942,7 @@ Conversely, when queried, the primitive returns \type{0} if the tag's
value is \type{no_tag}, \type{1} if \type{lig_tag} is set, \type{2} if
\type{list_tag} is set or \type{4} (not~3) if \type{ext_tag} is set.
-\pdftexprimitive {\Syntax {\Tex {\pdfgentounicode} \Whatever{integer}}}
+\pdftexprimitive{\Syntax{\Tex{\pdfgentounicode} \Whatever{integer}}}
By default, \PDFTEX\ does not include a \type{/ToUnicode} resource when
including fonts in the output. Such a resource (also called a CMap
@@ -3560,7 +2960,8 @@ follows: for each glyph in the font, look for its \type{ToUnicode} value
in a global hash table. By default that global hash table is empty;
entries are added to the table using the following command:
-\pdftexprimitive {\Syntax {\Tex {\pdfglyphtounicode} \Something{general text} \Something{general text}}}
+\pdftexprimitive{\Syntax{\Tex{\pdfglyphtounicode} \Something{general text}
+ \Something{general text}}}
The first argument is the name of a glyph, the second is a string of Unicode
numeric values denoting characters. For instance:
@@ -3586,7 +2987,7 @@ glyph names. So, for practical purposes, one would probably want:
effect.
-\pdftexprimitive {\Syntax {\Tex {\pdfnobuiltintounicode} \Something{font}}}
+\pdftexprimitive{\Syntax{\Tex{\pdfnobuiltintounicode} \Something{font}}}
The primary purpose of this command is to prevent \PDFTEX\ from
generating the \type{ToUnicode}/CMap resource for the given font when
@@ -3604,8 +3005,8 @@ Minimal example:
\introduced{1.40.11}
-\pdftexprimitive {\Syntax {\Tex {\pdfinterwordspaceon}}}
-\pdftexprimitive {\Syntax {\Tex {\pdfinterwordspaceoff}}}
+\pdftexprimitive{\Syntax{\Tex{\pdfinterwordspaceon}}}
+\pdftexprimitive{\Syntax{\Tex{\pdfinterwordspaceoff}}}
These commands create corresponding whatsit nodes which turn on/off
generation of faked interword spaces in the output. This allows for
@@ -3634,7 +3035,7 @@ Back to text with no interword spaces.
\stoptyping
\introduced{1.40.15}
-\pdftexprimitive {\Syntax {\Tex {\pdffakespace}}}
+\pdftexprimitive{\Syntax{\Tex{\pdffakespace}}}
Insert a faked interword space to the output, regardless of the value of
\type{\pdfinterwordspaceon} and \type{\pdfinterwordspaceoff}. Example:
@@ -3651,15 +3052,14 @@ Text with no interword \pdffakespace\pdffakespace spaces.
Controlling spacing before and after characters was introduced in version 1.30,
mostly to handle punctuation rules in different languages.
-\pdftexprimitive{\Syntax {\Tex{\pdfadjustinterwordglue} \Whatever{integer}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfadjustinterwordglue} \Whatever{integer}}}
\bookmark{\tex{pdfadjustinterwordglue}}
If positive, adjustment of interword glue is enabled and controlled by the
following three primitives.
-\pdftexprimitive {\Syntax {\Tex {\knbscode} \Something{font} \Something{8-bit number} \Whatever{integer}}}
-
+\pdftexprimitive{\Syntax{\Tex{\knbscode} \Something{font}
+ \Something{8-bit number} \Whatever{integer}}}
\bookmark{\tex{knbscode}}
The amount of space, in thousandths of an em, added to the glue following
@@ -3672,27 +3072,26 @@ increased by .2\,em.
\knsbcode\font`\.=200
\stoptyping
-\pdftexprimitive {\Syntax {\Tex {\stbscode} \Something{font} \Something{8-bit number} \Whatever{integer}}}
-
+\pdftexprimitive{\Syntax{\Tex{\stbscode} \Something{font}
+ \Something{8-bit number} \Whatever{integer}}}
\bookmark{\tex{stbscode}}
This works like \type{\knbscode}, but applies to the stretch component of
the following glue.
-\pdftexprimitive {\Syntax {\Tex {\shbscode} \Something{font} \Something{8-bit number} \Whatever{integer}}}
-
+\pdftexprimitive{\Syntax{\Tex{\shbscode} \Something{font}
+ \Something{8-bit number} \Whatever{integer}}}
\bookmark{\tex{shbscode}}
Like \type{\stbscode}, but for the shrink component.
-\pdftexprimitive{\Syntax {\Tex{\pdfprependkern} \Whatever{integer}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfprependkern} \Whatever{integer}}}
\bookmark{\tex{pdfprependkern}}
If positive, automatic insertion of kerns before characters is enabled.
-\pdftexprimitive {\Syntax {\Tex {\knbccode} \Something{font} \Something{8-bit number} \Whatever{integer}}}
-
+\pdftexprimitive{\Syntax{\Tex{\knbccode} \Something{font}
+ \Something{8-bit number} \Whatever{integer}}}
\bookmark{\tex{knbccode}}
The width of the kern, in thousandths of an em, inserted before a character.
@@ -3705,25 +3104,24 @@ following code, a .15\,em-kern will be inserted before all question marks
\knbccode\font`\?=150
\stoptyping
-\pdftexprimitive{\Syntax {\Tex{\pdfappendkern} \Whatever{integer}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfappendkern} \Whatever{integer}}}
\bookmark{\tex{pdfappendkern}}
Same as \type{\pdfprependkern}, but for kerns inserted after characters.
-\pdftexprimitive {\Syntax {\Tex {\knaccode} \Something{font} \Something{8-bit number} \Whatever{integer}}}
-
+\pdftexprimitive{\Syntax{\Tex{\knaccode} \Something{font}
+ \Something{8-bit number} \Whatever{integer}}}
\bookmark{\tex{knaccode}}
-Same as \type{\knbccode}, except the kern is inserted after the character.
-Such a kern is required for instance after a left guillemet in French punctuation.
+Same as \type{\knbccode}, except the kern is inserted after the
+character. Such a kern is required for instance after a left guillemet
+in French punctuation.
%***********************************************************************
\subsection{Vertical adjustments}
-\pdftexprimitive {\Syntax {\Tex{\pdfignoreddimen} \Whatever{dimension}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfignoreddimen} \Whatever{dimen}}}
\bookmark{\tex{pdfignoreddimen}}
This is the dimension which must assigned to the following four primitives
@@ -3732,8 +3130,7 @@ with care since it also influences when a previous paragraph's depth is ignored
(for instance, the plain \TEX\ macro \type{\nointerlineskip} should be
modified accordingly).
-\pdftexprimitive {\Syntax {\Tex {\pdffirstlineheight} \Whatever{dimension}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdffirstlineheight} \Whatever{dimen}}}
\bookmark{\tex{pdffirstlineheight}}
This parameter specifies the height of the first line of a paragraph,
@@ -3742,22 +3139,19 @@ called, and ignored when set to \type{\pdfignoreddimen}. By default,
it is set to \type{-1000pt}, so it is ignored as long as the value
of \type{\pdfignoreddimen} is the same.
-\pdftexprimitive {\Syntax {\Tex {\pdflastlinedepth} \Whatever{dimension}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdflastlinedepth} \Whatever{dimen}}}
\bookmark{\tex{pdflastlinedepth}}
This is similar to the previous parameter, but affects the last line's
depth of a paragraph.
-\pdftexprimitive {\Syntax {\Tex {\pdfeachlineheight} \Whatever{dimension}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfeachlineheight} \Whatever{dimen}}}
\bookmark{\tex{pdfeachlineheight}}
Similar to \type{\pdffirstlineheight}, but for all lines of a paragraph,
including the first one, unless \type{\pdffirstlineheight} is specified.
-\pdftexprimitive {\Syntax {\Tex {\pdfeachlinedepth} \Whatever{dimension}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfeachlinedepth} \Whatever{dimen}}}
\bookmark{\tex{pdfeachlinedepth}}
Like the preceding parameter, but for depth.
@@ -3766,8 +3160,8 @@ Like the preceding parameter, but for depth.
\subsection{\PDF\ objects}
-\pdftexprimitive {\Syntax {\Tex {\pdfobj} \Something{object type spec}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfobj} \Something{object type spec}
+ \Modelist{h, v, m}}}
\bookmark{\tex{pdfobj}}
This command creates a raw \PDF\ object that is written to the \PDF\
@@ -3799,15 +3193,14 @@ is preceded by \type{\immediate}. Nothing is appended to the list being
built. The number of the most recently created object is accessible via
\type{\pdflastobj}.
-\pdftexprimitive {\Syntax {\Tex {\pdflastobj} \Whatever{read||only integer}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdflastobj} \Whatever{read||only integer}}}
\bookmark{\tex{pdflastobj}}
This command returns the object number of the last object created by \type
{\pdfobj}.
-\pdftexprimitive {\Syntax {\Tex {\pdfrefobj} \Something{object number}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfrefobj} \Something{object number}
+ \Modelist{h, v, m}}}
\bookmark{\tex{pdfrefobj}}
This command appends a whatsit node to the list being built. When the whatsit
@@ -3819,18 +3212,16 @@ to the \PDF\ output if it has not been written yet.
\subsection{Page and pages objects}
-\pdftexprimitive {\Syntax {\Tex {\pdfpagesattr} \Whatever{tokens}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfpagesattr} \Whatever{tokens}}}
\bookmark{\tex{pdfpagesattr}}
-\PDFTEX\ expands this token list when it finishes the \PDF\ output and adds
-the resulting character stream to the root \type{Pages} object. When defined,
-these are applied to all pages in the document. Some examples of attributes
-are \type{/MediaBox}, the rectangle specifying the natural size of the page,
-\type{/CropBox}, the rectangle specifying the region of the page being
-displayed and printed, and \type{/Rotate}, the number of degrees (in
-multiples of 90) the page should be rotated clockwise when it is displayed or
-printed.
+\PDFTEX\ expands this token list when it finishes the \PDF\ output and
+adds the resulting character stream to the root \type{Pages}
+object. When defined, these are applied to all pages in the
+document. Some examples of attributes are \type{/CropBox}, the rectangle
+specifying the region of the page being displayed and printed, and
+\type{/Rotate}, the number of degrees (in multiples of 90) the page
+should be rotated clockwise when it is displayed or printed.
% /MediaBox is not a good example, since will never take an effect
@@ -3840,8 +3231,7 @@ printed.
/CropBox [0 0 612 792] } % the crop size of all pages (in bp)
\stoptyping
-\pdftexprimitive {\Syntax {\Tex {\pdfpageattr} \Whatever{tokens}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfpageattr} \Whatever{tokens}}}
\bookmark{\tex{pdfpageattr}}
This is similar to \type{\pdfpagesattr}, but has priority over it.
@@ -3849,8 +3239,18 @@ It can be used to override any attribute given by \type{\pdfpagesattr}
for individual pages. The token list is expanded when \PDFTEX\ ships out
a page. The contents are added to the attributes of the current page.
-\pdftexprimitive {\Syntax {\Tex {\pdfpageref} \Something{page number} \Whatever{expandable}}}
+\pdftexprimitive{\Syntax{\Tex{\pdfpageresources} \Whatever{tokens}}}
+\bookmark{\tex{pdfpageresources}}
+These tokens are added to the resource dictionary for all pages, before
+the font, XOBject, and other resources.
+
+\starttyping
+\pdfpageresources{/MyPageResourceAttribute /MyValue}
+\stoptyping
+
+\pdftexprimitive{\Syntax{\Tex{\pdfpageref} \Something{page number}
+ \Whatever{expandable}}}
\bookmark{\tex{pdfpageref}}
This primitive expands to the number of the page object that contains
@@ -3879,9 +3279,9 @@ These commands behave similarly to \type{\pdfobj}, \type{\pdfrefobj}
and \type{\pdflastobj}, but instead of taking raw \PDF\ code, they handle
text typeset by \TEX.
-\pdftexprimitive {\Syntax {\Tex {\pdfxform} \Optional{\Something{attr
-spec}} \Optional{\Something{resources spec}} \Something{box number}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfxform} \Optional{\Something{attr spec}}
+ \Optional{\Something{resources spec}} \Something{box number}
+ \Modelist{h, v, m}}}
\bookmark{\tex{pdfxform}}
This command creates a form XObject corresponding to the contents of the
@@ -3899,34 +3299,33 @@ to the resources dictionary of the form XObject. The text given by
other entries of the form dictionary and|/|or the resources dictionary
and takes priority over later ones.
-\pdftexprimitive {\Syntax {\Tex {\pdfrefxform} \Something{object number}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfrefxform} \Something{object number}
+ \Modelist{h, v, m}}}
\bookmark{\tex{pdfrefxform}}
The form XObject is kept in memory and will be written to the \PDF\
output only when its object number is referred to by \type{\pdfrefxform}
or when \type{\pdfxform} is preceded by \type{\immediate}. Nothing is
appended to the list being built. The number of the most recently created
-form XObject is accessible via \type {\pdflastxform}.
+form XObject is accessible via \type{\pdflastxform}.
When issued, \type{\pdfrefxform} appends a whatsit node to the list being
built. When the whatsit node is searched at shipout time, \PDFTEX\ will
write the form \Something{object number} to the \PDF\ output if it is
not written yet.
-\pdftexprimitive {\Syntax {\Tex {\pdflastxform}} \Whatever{read||only integer}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdflastxform} \Whatever{read||only integer}}}
\bookmark{\tex{pdflastxform}}
The object number of the most recently created form XObject is accessible
-via \type {\pdflastxform}.
+via \type{\pdflastxform}.
As said, this feature can be used for reusing information. This mechanism
also plays a role in typesetting fill||in forms. Such widgets sometimes
depends on visuals that show up on user request, but are hidden otherwise.
-\pdftexprimitive {\Syntax {\Tex {\pdfxformname} \Something{object number} \Whatever{expandable}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfxformname} \Something{object number}
+ \Whatever{expandable}}}
\bookmark{\tex{pdfxformname}}
In \PDF\ files produced by \PDFTEX\ one can recognize a form Xobject by
@@ -3945,16 +3344,15 @@ XObjects. In \PDFTEX\ this mechanism is accessed by means of \type{\pdfxform},
\type{\pdflastxform} and \type{\pdfrefxform}. A special kind of XObjects
are bitmap graphics and for manipulating them similar commands are provided.
-\pdftexprimitive {\Syntax {
- \Tex {\pdfximage}
+\pdftexprimitive{\Syntax{\Tex{\pdfximage}
\Optional{\Something{rule spec}}
\Optional{\Something{attr spec}}
\Optional{\Something{page spec}}
\Optional{\Something{colorspace spec}}
\Optional{\Something{pdf box spec}}
\Something{general text}
+ \Modelist{h, v, m}
}}
-
\bookmark{\tex{pdfximage}}
This command creates an image object. The dimensions of the image can be
@@ -3986,7 +3384,7 @@ the \eg\ \type{\input} primitive, the filename is supplied between
braces.
The image type is specified by the extension of the given file name:
-\type {.png} stands for \PNG\ image, \type{.jpg} (or \type{.jpeg}) for
+\type{.png} stands for \PNG\ image, \type{.jpg} (or \type{.jpeg}) for
\JPEG, \type{.jbig2} (preferred, but \type{.jb2} works also) for \JBIGTWO,
and \type{.pdf} for \PDF\ file. But once \PDFTEX\ has opened the file,
it checks the file type first by looking to the magic number at the
@@ -4016,8 +3414,7 @@ colorspace for the image being included). This feature works for \JPEG\
images only. \PNG s are \RGB\ palettes, \JBIG2 s are bitonal, and \PDF\
images have always self||contained color space information.
-\pdftexprimitive {\Syntax {\Tex {\pdfrefximage} \Something{integer}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfrefximage} \Something{object number}}}
\bookmark{\tex{pdfrefximage}}
The image is kept in memory and will be written to the \PDF\ output only when
@@ -4026,19 +3423,17 @@ preceded by \type{\immediate}. Nothing is appended to the list being built.
\type{\pdfrefximage} appends a whatsit node to the list being built. When
the whatsit node is searched at shipout time, \PDFTEX\ will write the image
-with number \Something{integer} to the \PDF\ output if it has not been
+with number \Something{object number} to the \PDF\ output if it has not been
written yet.
-\pdftexprimitive {\Syntax {\Tex {\pdflastximage} \Whatever{read||only
-integer}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdflastximage} \Whatever{read||only integer}}}
\bookmark{\tex{pdflastximage}}
The number of the most recently created XObject image is accessible via \type
{\pdflastximage}.
-\pdftexprimitive {\Syntax {\Tex {\pdfximagebbox} \Something{integer} \Something{integer} \Whatever{expandable}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfximagebbox} \Something{integer}
+ \Something{integer} \Whatever{expandable}}}
\bookmark{\tex{pdfximagebbox}}
The dimensions of the bounding box of a \PDF\ image loaded with
@@ -4053,17 +3448,15 @@ dimensions as follows:
\pdfximagebbox\pdflastximage 4 % Returns upper-right y
\stoptyping
-\pdftexprimitive {\Syntax {\Tex {\pdflastximagecolordepth} \Whatever{read||only
-integer}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdflastximagecolordepth}
+ \Whatever{read||only integer}}}
\bookmark{\tex{pdflastximagecolordepth}}
The color depth (\type{1} for 1-bit images, \type{2} for 2-bit images,
and so on) of the last image accessed with \type{\pdfximage}.
-\pdftexprimitive {\Syntax {\Tex {\pdflastximagepages} \Whatever{read||only
-integer}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdflastximagepages}
+ \Whatever{read||only integer}}}
\bookmark{\tex{pdflastximagepages}}
This read||only register returns the highest page number from a file
@@ -4071,8 +3464,7 @@ previously accessed via the \type{\pdfximage} command.
This is useful only for \PDF\ files; it always returns \type{1}
for \PNG, \JPEG, or \JBIGTWO\ files.
-\pdftexprimitive {\Syntax {\Tex {\pdfimageresolution} \Whatever{integer}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfimageresolution} \Whatever{integer}}}
\bookmark{\tex{pdfimageresolution}}
The integer \type{\pdfimageresolution} parameter (unit: dots per
@@ -4098,8 +3490,7 @@ dimensions of \JPEG\ images in \EXIF\ format (unless at least one
dimension is stated explicitly); the resolution values coming with
\EXIF\ files are currently ignored.
-\pdftexprimitive {\Syntax {\Tex {\pdfpagebox} \Whatever{integer}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfpagebox} \Whatever{integer}}}
\bookmark{\tex{pdfpagebox}}
When \PDF\ files are included, the command \type{\pdfximage} allows the
@@ -4109,8 +3500,7 @@ page box defaults to the value of \type{\pdfpagebox} as follows:
(1)~media box, (2)~crop box, (3)~bleed box, (4)~trim box, and
(5)~artbox.
-\pdftexprimitive {\Syntax {\Tex {\pdfforcepagebox} \Whatever{integer}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfforcepagebox} \Whatever{integer}}}
\bookmark{\tex{pdfforcepagebox}}
%- It is now possible to specify the pdf page box to use when including pdfs.
@@ -4136,8 +3526,7 @@ starting from \PDFTEX\ 1.30.0, as a shortened synonym of obsolete
now considered obsolete --- a mixture of \type{\pdfpagebox} and
\Something{image attr spec} is better.
-\pdftexprimitive {\Syntax {\Tex {\pdfinclusionerrorlevel} \Whatever{integer}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfinclusionerrorlevel} \Whatever{integer}}}
\bookmark{\tex{pdfinclusionerrorlevel}}
This controls the behaviour of \PDFTEX\ when a \PDF\ file is included
@@ -4150,8 +3539,7 @@ It was originally a shortened synonym of
\type{\pdfoptionpdfinclusionerrorlevel}, which is now obsolete.
\introduced{1.30.0}
-\pdftexprimitive {\Syntax {\Tex {\pdfimagehicolor} \Whatever{integer}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfimagehicolor} \Whatever{integer}}}
\bookmark{\tex{pdfimagehicolor}}
This primitive, when set to~1, enables embedding of \PNG\ images with
@@ -4166,19 +3554,17 @@ the default value of \type{\pdfimagehicolor} is~1. If specified, the
parameter must appear before any data is written to the \PDF\ output.
\introduced{1.30.0}
-\pdftexprimitive {\Syntax {\Tex {\pdfimageapplygamma} \Whatever{integer}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfimageapplygamma} \Whatever{integer}}}
\bookmark{\tex{pdfimageapplygamma}}
This primitive, when set to~1, enables gamma correction while embedding
-\PNG\ images, taking the values of the primitives \type {\pdfgamma} as
+\PNG\ images, taking the values of the primitives \type{\pdfgamma} as
well as the gamma value embedded in the \PNG\ image into account. When
\type{\pdfimageapplygamma} is set to~0, no gamma correction is
performed. If specified, the parameter must appear before any data is
written to the \PDF\ output. \introduced{1.30.0}
-\pdftexprimitive {\Syntax {\Tex {\pdfgamma} \Whatever{integer}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfgamma} \Whatever{integer}}}
\bookmark{\tex{pdfgamma}}
This primitive defines the `device gamma' for \PDFTEX. Values are in
@@ -4195,8 +3581,7 @@ If specified, the parameter must appear before any data is written to the
\PDF\ output.
\introduced{1.30.0}
-\pdftexprimitive {\Syntax {\Tex {\pdfimagegamma} \Whatever{integer}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfimagegamma} \Whatever{integer}}}
\bookmark{\tex{pdfimagegamma}}
This primitive gives a default `assumed gamma' value for \PNG\ images.
@@ -4213,8 +3598,7 @@ If specified, the parameter must appear before any data is written to the
\PDF\ output.
\introduced{1.30.0}
-\pdftexprimitive {\Syntax {\Tex {\pdfpxdimen} \Whatever{dimen}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfpxdimen} \Whatever{dimen}}}
\bookmark{\tex{pdfpxdimen}}
While working with bitmap graphics or typesetting electronic documents,
@@ -4241,8 +3625,7 @@ the dimension 1\,px as number of scaled points, defaulting to 65536
(1\,px equal to 65536\,sp~$=$~1\,pt). Starting from \PDFTEX\ 1.40.0,
\type{\pdfpxdimen} is now a real dimension parameter.
-\pdftexprimitive {\Syntax {\Tex{\pdfinclusioncopyfonts} \Whatever{integer}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfinclusioncopyfonts} \Whatever{integer}}}
\bookmark{\tex{pdfinclusioncopyfonts}}
If positive, this parameter forces \PDFTEX\ to include fonts from a \PDF\
@@ -4251,9 +3634,8 @@ disk. Bigger files might be created, but included \PDF\ files are sure to
be embedded with the adequate fonts; indeed, the fonts on disk might be
different from the embedded ones, and glyphs might be missing.
-\pdftexprimitive {\Syntax {\Tex {\pdfsuppresswarningpagegroup}
-\Whatever{integer}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfsuppresswarningpagegroup}
+ \Whatever{integer}}}
\bookmark{\tex{pdfsuppresswarningpagegroup}}
Ordinarily, \PDFTEX\ gives a warning when more than one included \PDF\
@@ -4287,8 +3669,8 @@ area involved on which one can click, or when moved over some action occurs.
annotations can be supported using the next two general annotation
primitives.
-\pdftexprimitive {\Syntax {\Tex {\pdfannot} \Something{annot type spec}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfannot} \Something{annot type spec}
+ \Modelist{h, v, m}}}
\bookmark{\tex{pdfannot}}
This command appends a whatsit node corresponding to an annotation to
@@ -4301,9 +3683,7 @@ text} is inserted as raw \PDF\ code to the contents of annotation. The
annotation is written out only if the corresponding whatsit node is
searched at shipout time.
-\pdftexprimitive {\Syntax {\Tex {\pdflastannot} \Whatever{read||only
-integer}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdflastannot} \Whatever{read||only integer}}}
\bookmark{\tex{pdflastannot}}
This primitive returns the object number of the last annotation created by
@@ -4321,8 +3701,8 @@ page. The main reason for this is that \PDF\ maintains a dedicated list of
these annotations |<|and some more when optimized|>| for the sole purpose of
speed.
-\pdftexprimitive {\Syntax {\Tex {\pdfdest} \Something{dest spec}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfdest} \Something{dest spec}
+ \Modelist{h, v, m}}}
\bookmark{\tex{pdfdest}}
This primitive appends a whatsit node which establishes a destination
@@ -4352,26 +3732,29 @@ one of those mentioned in \in{table}[appearance].
{Options for display of outline and destinations.}
{\getbuffer}
-The specification \Literal {xyz} can optionally be followed by \Literal
+The specification \Literal{xyz} can optionally be followed by \Literal
{zoom} \Something{integer} to provide a fixed zoom||in. The \Something
{integer} is processed like \TEX\ magnification, i.\,e.\ 1000 is the
-normal page view. When \Literal {zoom} \Something{integer} is given,
+normal page view. When \Literal{zoom} \Something{integer} is given,
the zoom factor changes to 0.001 of the \Something{integer} value,
otherwise the current zoom factor is kept unchanged.
The destination is written out only if the corresponding whatsit node is
searched at shipout time.
-\pdftexprimitive {\Syntax {\Tex {\pdfstartlink} \Optional{\Something{rule
-spec}} \Optional{\Something{attr spec}} \Something{action spec}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfstartlink}
+ \Optional{\Something{rule spec}}
+ \Optional{\Something{attr spec}}
+ \Something{action spec}
+ \Modelist{h, m}
+}}
\bookmark{\tex{pdfstartlink}}
This primitive is used along with \type{\pdfendlink} and appends
a whatsit node corresponding to the start of a hyperlink. The whatsit
node representing the end of the hyperlink is created by
\type{\pdfendlink}. The dimensions of the link are handled in the
-similar way as in \type{\pdfannot}. Both \type {\pdfstartlink} and
+similar way as in \type{\pdfannot}. Both \type{\pdfstartlink} and
\type{\pdfendlink} must be in the same level of box nesting. A hyperlink
with running width can be multi||line or even multi||page, in which case
all horizontal boxes with the same nesting level as the boxes containing
@@ -4412,8 +3795,7 @@ A \Something{thread-action spec} performs an article thread reading. The
thread identifier is similar to the destination identifier. A thread can be
performed in another \PDF\ file by specifying a \Something{file spec}\unkern.
-\pdftexprimitive {\Syntax {\Tex {\pdfendlink}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfendlink} \Modelist{h, m}}}
\bookmark{\tex{pdfendlink}}
This primitive ends a link started with \type{\pdfstartlink}. All text
@@ -4421,31 +3803,25 @@ between \type{\pdfstartlink} and \type{\pdfendlink} will be treated as part
of this link. \PDFTEX\ may break the result across lines (or pages), in which
case it will make several links with the same content.
-\pdftexprimitive {\Syntax {\Tex {\pdflastlink} \Whatever{read||only
-integer}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdflastlink} \Whatever{read||only integer}}}
\bookmark{\tex{pdflastlink}}
This primitive returns the object number of the last link created by
\type{\pdfstartlink} (analogous to \type{\pdflastannot}).
\introduced{1.40.0}
-\pdftexprimitive {\Syntax {\Tex {\pdflinkmargin} \Whatever{dimension}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdflinkmargin} \Whatever{dimen}}}
\bookmark{\tex{pdflinkmargin}}
This dimension parameter specifies the margin of the box representing
a hyperlink and is read when a page containing hyperlinks is shipped out.
-\pdftexprimitive {\Syntax {\Tex {\pdfdestmargin} \Whatever{dimension}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfdestmargin} \Whatever{dimen}}}
\bookmark{\tex{pdfdestmargin}}
Margin added to the dimensions of the rectangle around the destinations.
-\pdftexprimitive {\Syntax {\Tex {\pdfsuppresswarningdupdest}
-\Whatever{integer}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfsuppresswarningdupdest} \Whatever{integer}}}
\bookmark{\tex{pdfsuppresswarningdupdest}}
Ordinarily, \PDFTEX\ gives a warning when the same destination is used
@@ -4459,10 +3835,13 @@ parameter to a positive number. \introduced{1.40.13}
\subsection{Bookmarks}
-\pdftexprimitive {\Syntax {\Tex {\pdfoutline}
-\Optional{\Something{attr spec}} \Something{action spec}
-\Optional{\Literal {count} \Something{integer}} \Something{general text}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfoutline}
+ \Optional{\Something{attr spec}}
+ \Something{action spec}
+ \Optional{\Literal{count} \Something{integer}}
+ \Something{general text}
+ \Modelist{h, v, m}
+}}
\bookmark{\tex{pdfoutline}}
This primitive creates an outline (or bookmark) entry. The first parameter
@@ -4479,19 +3858,17 @@ is written to the \PDF\ output immediately.
\subsection{Article threads}
-\pdftexprimitive {\Syntax {\Tex {\pdfthread}
-\Optional{\Something{rule spec}} \Optional
-{\Something{attr spec}} \Something{id spec}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfthread} \Optional{\Something{rule spec}}
+ \Optional{\Something{attr spec}} \Something{id spec} \Modelist{h, v, m}}}
\bookmark{\tex{pdfthread}}
Defines a bead within an article thread. Thread beads with same
identifiers (spread across the document) will be joined together.
-\pdftexprimitive {\Syntax {\Tex {\pdftstarthread}
-\Optional{\Something{rule spec}} \Optional
-{\Something{attr spec}} \Something{id spec}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdftstartthread}
+ \Optional{\Something{rule spec}}
+ \Optional{\Something{attr spec}}
+ \Something{id spec} \Modelist{v, m}}}
\bookmark{\tex{pdfstartthread}}
This uses the same syntax as \type{\pdfthread}, apart that it must be
@@ -4505,14 +3882,12 @@ into the thread, which is probably not what you want. To avoid such
unconsidered behaviour, it's often enough to wrap boxes that shouldn't
belong to the thread by a box to change their box nesting level.
-\pdftexprimitive {\Syntax {\Tex {\pdfendthread}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfendthread} \Modelist{v, m}}}
\bookmark{\tex{pdfendthread}}
This ends an article thread started before by \type{\pdfstartthread}.
-\pdftexprimitive {\Syntax {\Tex {\pdfthreadmargin} \Whatever{dimension}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfthreadmargin} \Whatever{dimen}}}
\bookmark{\tex{pdfthreadmargin}}
Specifies a margin to be added to the dimensions of a bead within
@@ -4522,9 +3897,11 @@ an article thread.
\subsection{Literals and specials}
-\pdftexprimitive {\Syntax {\Tex {\pdfliteral} \Optional{\Something {pdfliteral spec}}
-\Something{general text}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfliteral}
+ \Optional{\Something{pdfliteral spec}}
+ \Something{general text}
+ \Modelist{h, v, m}
+ }}
\bookmark{\tex{pdfliteral}}
Like \type{\special} in normal \TEX, this command inserts raw
@@ -4533,7 +3910,7 @@ transformation. This primitive is heavily used in the \METAPOST\
inclusion macros. Normally \PDFTEX\ ends a text section in the \PDF\
output and sets the transformation matrix to the current location on the
page before inserting \Something{general text}\unkern, however this can be
-turned off by giving the optional keyword \Literal {direct}. This command
+turned off by giving the optional keyword \Literal{direct}. This command
appends a whatsit node to the list being built. \Something{general text}
is expanded when the whatsit node is created and not when it is shipped
out, as with \type{\special}.
@@ -4551,32 +3928,33 @@ origin (lower||left corner of the page) and can be safely enclosed with
this within a \type{BT ET} block.
% HE: \unkern is a kludge here; wanted to have tight "{pdf:"
-\pdftexprimitive {\Syntax {\Tex {\special} \Lbrace\unkern\type{pdf:} \Something{text} \Rbrace}}
-
+\pdftexprimitive{\Syntax{\Tex{\special} \Lbrace\unkern\Literal{pdf:}
+ \Something{text} \Rbrace}}
\bookmark{\tex{special}}
This is equivalent to \Syntax{\Tex{\pdfliteral} \Lbrace \Something{text}
\Rbrace}.
-\pdftexprimitive {\Syntax {\Tex {\special} \Lbrace\unkern\type{pdf:direct:} \Something{text} \Rbrace}}
-
+\pdftexprimitive{\Syntax{\Tex{\special} \Lbrace\unkern\Literal{pdf:direct:}
+ \Something{text} \Rbrace}}
\bookmark{\tex{special\ direct}}
This is equivalent to \Syntax{\Tex{\pdfliteral} \Literal{direct} \Lbrace
\Something{text} \Rbrace}.
-\pdftexprimitive {\Syntax {\Tex {\special} \Lbrace\unkern\type{pdf:page:} \Something{text} \Rbrace}}
-
+\pdftexprimitive{\Syntax{\Tex{\special} \Lbrace\unkern\Literal{pdf:page:}
+ \Something{text} \Rbrace}}
\bookmark{\tex{special\ page}}
-This is equivalent to \Syntax{\Tex{\pdfliteral} \Literal{page} \Lbrace \Something{text} \Rbrace}.
+This is equivalent to \Syntax{\Tex{\pdfliteral} \Literal{page} \Lbrace
+\Something{text} \Rbrace}.
%***********************************************************************
\subsection{Strings}
-\pdftexprimitive {\Syntax {\Tex {\pdfescapestring} \Something {general text} \Whatever{expandable}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfescapestring} \Something{general text}
+ \Whatever{expandable}}}
\bookmark{\tex{pdfescapestring}}
Starting from version 1.30.0, \PDFTEX\ provides a mechanism for converting
@@ -4590,8 +3968,8 @@ expanded to \type{Text\040\(1\)}. This ensures a literal interpretation of the
text by the \PDF\ viewer.
\introduced{1.30.0}
-\pdftexprimitive {\Syntax {\Tex {\pdfescapename} \Something {general text} \Whatever{expandable}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfescapename} \Something{general text}
+ \Whatever{expandable}}}
\bookmark{\tex{pdfescapename}}
In analogy to \type{\pdfescapestring}, \type{\pdfescapename} replaces each
@@ -4601,34 +3979,33 @@ interpretation of the text if used as a \PDF\ name object. In example,
\type{Text (1)} will be replaced by \type{Text#20#281#29}.
\introduced{1.30.0}
-\pdftexprimitive {\Syntax {\Tex {\pdfescapehex} \Something {general text} \Whatever{expandable}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfescapehex} \Something{general text}
+ \Whatever{expandable}}}
\bookmark{\tex{pdfescapehex}}
This command converts each character of \Something{general text} into its
hexadecimal representation. Each character of the argument becomes a pair of
hexadecimal digits. \introduced{1.30.0}
-\pdftexprimitive {\Syntax {\Tex {\pdfunescapehex} \Something {general text} \Whatever{expandable}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfunescapehex} \Something{general text}
+ \Whatever{expandable}}}
\bookmark{\tex{pdfunescapehex}}
-This command treats each character pair of \Something {general text} as
+This command treats each character pair of \Something{general text} as
a hexadecimal number and returns an \ASCII\ character of this code.
\introduced{1.30.0}
-\pdftexprimitive {\Syntax {\Tex {\pdfstrcmp} \Something{general text}
-\Something{general text} \Whatever{expandable}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfstrcmp} \Something{general text}
+ \Something{general text} \Whatever{expandable}}}
\bookmark{\tex{pdfstrcmp}}
This command compares two strings and expands to \type{0} if the strings
are equal, to \type{-1} if the first string ranks before the second, and
to \type{1} otherwise. \introduced{1.30.0}
-\pdftexprimitive {\Syntax {\Tex {\pdfmatch} \Optional{\Literal{icase}} \Optional{\Literal{subcount} \Something{integer}}
-\Something{general text} \Something{general text} \Whatever{expandable}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfmatch} \Optional{\Literal{icase}}
+ \Optional{\Literal{subcount} \Something{integer}} \Something{general text}
+ \Something{general text} \Whatever{expandable}}}
\bookmark{\tex{pdfmatch}}
This command implements pattern matching (using the syntax of \POSIX\
@@ -4639,8 +4016,8 @@ a match is found. With the \type{icase} option, the matching is
case-insensitive. The \type{subcount} option sets the size of the table
storing found (sub)patterns. \introduced{1.30.0}
-\pdftexprimitive {\Syntax {\Tex {\pdflastmatch} \Something{integer} \Whatever{expandable}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdflastmatch} \Something{integer}
+ \Whatever{expandable}}}
\bookmark{\tex{pdflastmatch}}
The matches found with \type{\pdfmatch} are stored in a table. This command
@@ -4663,21 +4040,11 @@ Entry~1 is empty because no match was found for \type{cd}, and entry~3
is empty because it exceeds the table's size, as set by \type{subcount}.
\introduced{1.30.0}
-\pdftexprimitive{\Syntax {\Tex {\pdfmdfivesum} \Something{general text}
-\Whatever{expandable}}}
-
-\bookmark{\tex{pdfmdfivesum}}
-
-This command expands to the \MDFIVE\ of \Something{general text} in uppercase
-hexadecimal format (same as \type{\pdfescapehex}).
-\introduced{1.30.0}
-
%***********************************************************************
\subsection{Numbers}
-\pdftexprimitive{\Syntax {\Tex {\ifpdfabsnum} \Whatever{expandable}}}
-
+\pdftexprimitive{\Syntax{\Tex{\ifpdfabsnum} \Whatever{expandable}}}
\bookmark{\tex{ifpdfabsnum}}
This conditional works like the standard \type{\ifnum}, except that it
@@ -4686,24 +4053,22 @@ shortcut for a couple of \type{\ifnum x<0} tests, as a primitive it is
considerably more friendly in usage and works a bit faster.
\introduced{1.40.0}
-\pdftexprimitive{\Syntax {\Tex {\ifpdfabsdim} \Whatever{expandable}}}
-
+\pdftexprimitive{\Syntax{\Tex{\ifpdfabsdim} \Whatever{expandable}}}
\bookmark{\tex{ifpdfabsdim}}
Analogous to \type{\ifpdfabsnum}, this conditional works like
\type{\ifdim}, except that it compares absolute values of
dimensions. \introduced{1.40.0}
-\pdftexprimitive{\Syntax {\Tex {\pdfuniformdeviate} \Something{number} \Whatever{expandable}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfuniformdeviate} \Something{number}
+ \Whatever{expandable}}}
\bookmark{\tex{pdfuniformdeviate}}
Generate a uniformly-distributed random integer value between 0
(inclusive) and \Something{number} (exclusive). This primitive expands
to a list of tokens. \introduced{1.30.0}
-\pdftexprimitive{\Syntax {\Tex {\pdfnormaldeviate} \Whatever{expandable}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfnormaldeviate} \Whatever{expandable}}}
\bookmark{\tex{pdfnormaldeviate}}
Generate a normally-distributed random integer with a mean of~0 and
@@ -4713,9 +4078,7 @@ the mean). About 95\% of results will be within two standard
deviations, and 99.7\% within three. This primitive expands to a list
of tokens. \introduced{1.30.0}
-\pdftexprimitive {\Syntax {\Tex {\pdfrandomseed}} \Whatever{read||only
-integer}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfrandomseed} \Whatever{read||only integer}}}
\bookmark{\tex{pdfrandomseed}}
You can use \type{\the\pdfrandomseed} to query the current seed value,
@@ -4724,8 +4087,7 @@ the seed is derived from the system time, and is not more than
1\,000\,999\,999 (this ensures that the value can be used with commands
like \type{\count}). \introduced{1.30.0}
-\pdftexprimitive{\Syntax {\Tex {\pdfsetrandomseed} \Something{number}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfsetrandomseed} \Something{number}}}
\bookmark{\tex{pdfsetrandomseed}}
Set the random seed (\type{\pdfrandomseed}) to a specific value,
@@ -4736,9 +4098,7 @@ allowing you to replay sequences of semi-randoms at a later moment.
\subsection{Timekeeping}
-\pdftexprimitive {\Syntax {\Tex {\pdfelapsedtime}} \Whatever{read||only
-integer}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfelapsedtime} \Whatever{read||only integer}}}
\bookmark{\tex{pdfelapsedtime}}
Return a number that represents the time elapsed from the moment of the
@@ -4749,8 +4109,7 @@ typeset. Of course, the command will never return a value greater than
the highest number available in \TeX: if the time exceeds 32767 seconds,
the constant value $2^{31}-1$ will be returned. \introduced{1.30.0}
-\pdftexprimitive{\type{\pdfresettimer}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfresettimer}}}
\bookmark{\tex{pdfresettimer}}
Reset the internal timer so that \type{\pdfelapsedtime}
@@ -4760,9 +4119,8 @@ starts returning micro||time from~0 again. \introduced{1.30.0}
\subsection{Files}
-\pdftexprimitive{\Syntax {\Tex {\pdffilemoddate} \Something{general text}
-\Whatever{expandable}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdffilemoddate} \Something{general text}
+ \Whatever{expandable}}}
\bookmark{\tex{pdffilemoddate}}
Expands to the modification date of file \Something{general text} in the same
@@ -4770,18 +4128,16 @@ format as for \type{\pdfcreationdate}, \eg\ it's {\tt \pdffilemoddate
{./pdftex-t.tex}} for the source of this manual.
\introduced{1.30.0}
-\pdftexprimitive{\Syntax {\Tex {\pdffilesize} \Something{general text}
-\Whatever{expandable}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdffilesize} \Something{general text}
+ \Whatever{expandable}}}
\bookmark{\tex{pdffilesize}}
Expands to the size of file \Something{general text}, \eg\ it's {\tt
\pdffilesize {./pdftex-t.tex}} for the source of this manual.
\introduced{1.30.0}
-\pdftexprimitive{\Syntax {\Tex {\pdfmdfivesum} file \Something{general text}
-\Whatever{expandable}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfmdfivesum} file \Something{general text}
+ \Whatever{expandable}}}
\bookmark{\tex{pdfmdfivesum\ file}}
Expands to the \MDFIVE\ of file \Something{general text} in uppercase
@@ -4789,10 +4145,9 @@ hexadecimal format (same as \type{\pdfescapehex}), \eg\ it's {\tt
\pdfmdfivesum file {./pdftex-t.tex}} for the source of this manual.
\introduced{1.30.0}
-\pdftexprimitive{\Syntax {\Tex {\pdffiledump} \Optional{\Literal{offset}
-\Something{number}} \Optional{\Literal{length} \Something{number}} \Something{general
-text} \Whatever{expandable}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdffiledump} \Optional{\Literal{offset}
+ \Something{number}} \Optional{\Literal{length}
+ \Something{number}} \Something{general text} \Whatever{expandable}}}
\bookmark{\tex{pdffiledump}}
Expands to the dump of the file \Something{general text} in uppercase
@@ -4808,10 +4163,8 @@ bytes of the source of this manual are {\tt \pdffiledump length 10
\PDFTEX\ 1.40.0 comes with color stack support (actually any graphic state
stack).
-\pdftexprimitive{\Syntax {
-\Tex {\pdfcolorstackinit} \Optional{\Literal{page}} \Optional{\Literal{direct}} \Something{general text}
-\Whatever{expandable}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfcolorstackinit} \Optional{\Literal{page}}
+ \Optional{\Literal{direct}} \Something{general text} \Whatever{expandable}}}
\bookmark{\tex{pdfcolorstackinit}}
The primitive initializes a new graphic stack and returns its number. Optional
@@ -4819,10 +4172,8 @@ The primitive initializes a new graphic stack and returns its number. Optional
beginning of every new page. Also optional \Literal{direct} has the same effect
as for \Tex{\pdfliteral} primitive. \introduced{1.40.0}
-\pdftexprimitive{\Syntax {
-\Tex {\pdfcolorstack} \Something{stack number} \Something{stack action}
-\Something{general text}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfcolorstack} \Something{stack number}
+ \Something{stack action} \Something{general text}}}
\bookmark{\tex{pdfcolorstack}}
The command operates on the stack of a given number. If \Something{stack
@@ -4845,8 +4196,7 @@ and restoring the current transformation matrix, remains unnoticed by
affected by such user-defined transformations. \PDFTEX\ 1.40.0 solves this
problem with three new primitives.
-\pdftexprimitive{\Syntax {\Tex {\pdfsetmatrix}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfsetmatrix}}}
\bookmark{\tex{pdfsetmatrix}}
Afine transformations are normally expressed with six numbers. First
@@ -4859,15 +4209,13 @@ by a space and assumes two position coordinates to be~0. In example,
degrees, inserting \type{0.87 -0.5 0.5 0.87 0 0 cm} into the content
stream. \introduced{1.40.0}
-\pdftexprimitive{\Syntax {\Tex {\pdfsave}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfsave}}}
\bookmark{\tex{pdfsave}}
The command saves the current transformation by inserting \type{q}
operator into the content stream. \introduced{1.40.0}
-\pdftexprimitive{\Syntax {\Tex {\pdfrestore}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfrestore}}}
\bookmark{\tex{pdfrestore}}
The command restores previously saved transformation by inserting \type{Q}
@@ -4879,16 +4227,15 @@ and end at the same group level. \introduced{1.40.0}
\subsection{Miscellaneous}
-\pdftexprimitive {\Syntax {\tex {ifincsname} \Whatever{expandable}}}
-
+\pdftexprimitive{\Syntax{\tex {ifincsname} \Whatever{expandable}}}
\bookmark{\tex{ifincsname}}
This conditional is true if evaluated inside \type{\csname ... \endcsname},
and false otherwise.
-\pdftexprimitive {\Syntax {\tex {ifpdfprimitive} \Something{control sequence} \Whatever{expandable}}}
-
+\pdftexprimitive{\Syntax{\tex {ifpdfprimitive} \Something{control sequence}
+ \Whatever{expandable}}}
\bookmark{\tex{ifpdfprimitive}}
This condition checks if the following control sequence has its
@@ -4897,16 +4244,14 @@ any other case (redefined, made \type{\undefined}, has never been
primitive) false is returned. \introduced{1.40.0}
-\pdftexprimitive {\Syntax {\Tex {\pdfcreationdate} \Whatever{expandable}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfcreationdate} \Whatever{expandable}}}
\bookmark{\tex{pdfcreationdate}}
Expands to the date string \PDFTEX\ uses in the info dictionary of the
document, \eg\ for this file {\tt\pdfcreationdate}. \introduced{1.30.0}
-\pdftexprimitive {\Syntax {\tex {pdfdraftmode} \Whatever{integer}}}
-
+\pdftexprimitive{\Syntax{\tex {pdfdraftmode} \Whatever{integer}}}
\bookmark{\tex{pdfdraftmode}}
When set to 1 (or set by the command-line switch \type{-draftmode})
@@ -4917,8 +4262,8 @@ don't care about the output, \eg\ just to get the \BIBTEX\ references
right. \introduced{1.40.0}
-\pdftexprimitive {\Syntax {\Tex{\pdfinsertht} \Something{integer} \Whatever{expandable}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfinsertht} \Something{integer}
+ \Whatever{expandable}}}
\bookmark{\tex{pdfinsertht}}
If \Something{integer} is the number of an insertion class, this command
@@ -4931,9 +4276,7 @@ Abc\footnote*{Whatever.}\par
\stoptyping
-\pdftexprimitive {\Syntax {\Tex {\pdflastxpos}} \Whatever{read||only
-integer}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdflastxpos} \Whatever{read||only integer}}}
\bookmark{\tex{pdflastxpos}}
This primitive returns an integer number representing the absolute $x$
@@ -4941,17 +4284,13 @@ coordinate of the last point marked by \type{\pdfsavepos}. The unit is
`scaled points' (sp).
-\pdftexprimitive {\Syntax {\Tex {\pdflastypos}} \Whatever{read||only
-integer}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdflastypos} \Whatever{read||only integer}}}
\bookmark{\tex{pdflastypos}}
-This primitive works analogously to \type{\pdflastxpos}, only returning
-the $y$ coordinate.
-
+Completely analogous to \type{\pdflastxpos}, returning the $y$ coordinate.
-\pdftexprimitive {\Syntax {\tex {pdfprimitive} \Something{control sequence}}}
+\pdftexprimitive{\Syntax{\tex {pdfprimitive} \Something{control sequence}}}
\bookmark{\tex{pdfprimitive}}
This command executes the primitive meaning of the following control
@@ -4962,9 +4301,7 @@ expandable, \type{\pdfprimitive} expands either. Otherwise
\type{\pdfprimitive} doesn't expand. \introduced{1.40.0}
-\pdftexprimitive {\Syntax {\Tex {\pdfretval} \Whatever{read||only
-integer}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfretval} \Whatever{read||only integer}}}
\bookmark{\tex{pdfretval}}
Set to $-1$ if \type{\pdfobj} ignores an invalid object number. Perhaps
@@ -4972,8 +4309,7 @@ this will be used to store the error status of other primitives in the
future.
-\pdftexprimitive {\Syntax {\Tex {\pdfsavepos}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfsavepos} \Modelist{h, v, m}}}
\bookmark{\tex{pdfsavepos}}
This primitive marks the current absolute ($x,y$) position on the
@@ -4988,9 +4324,7 @@ runs are required to utilize these primitives. Starting with
in \DVI\ mode.
-\pdftexprimitive {\Syntax {\Tex {\pdfshellescape} \Whatever{read||only
-integer}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdfshellescape} \Whatever{read||only integer}}}
\bookmark{\tex{pdfshellescape}}
This primitive is~1 if \type{\write18} is enabled, 2 if it is
@@ -4999,16 +4333,14 @@ restricted, and 0 otherwise. (\type{\write18} was
typeset.) \introduced{1.30.0}
-\pdftexprimitive {\Syntax {\Tex {\pdftexbanner} \Whatever{expandable}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdftexbanner} \Whatever{expandable}}}
\bookmark{\tex{pdftexbanner}}
Returns the \PDFTEX\ banner message, \eg\ for the version used here:
{\tt \pdftexbanner}. \introduced{1.20a}
-\pdftexprimitive {\Syntax {\Tex {\pdftexrevision} \Whatever{expandable}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdftexrevision} \Whatever{expandable}}}
\bookmark{\tex{pdftexrevision}}
\def\versplit#1#2#3{#1.#2#3}
@@ -5018,8 +4350,7 @@ Returns the revision number of \PDFTEX, \eg\ for \PDFTEX\ version
this document), it returns the number {\tt \pdftexrevision}.
-\pdftexprimitive {\Syntax {\Tex {\pdftexversion} \Whatever{read||only integer}}}
-
+\pdftexprimitive{\Syntax{\Tex{\pdftexversion} \Whatever{read||only integer}}}
\bookmark{\tex{pdftexversion}}
Returns the version of \PDFTEX\ multiplied by 100, \eg\ for \PDFTEX\
@@ -5027,8 +4358,7 @@ version \expandafter\versplit\the\pdftexversion.\pdftexrevision\ used to
produce this document, it returns {\tt \number\pdftexversion}.
-\pdftexprimitive {\Syntax {\Tex {\quitvmode}}}
-
+\pdftexprimitive{\Syntax{\Tex{\quitvmode}}}
\bookmark{\tex{quitvmode}}
The primitive instructs \PDFTEX\ to quit vertical mode and start
@@ -5039,19 +4369,21 @@ tokens list. No such risk while using \type{\quitvmode} instead.
\introduced{1.21a}
-\pdftexprimitive {\Syntax {\Tex {\vadjust}
- \Optional{\Something{pre spec}} \Something{filler}
- \Lbrace \Something{vertical mode material} \Rbrace }}
-
+\pdftexprimitive{\Syntax{\Tex{\vadjust}
+ \Optional{\Something{pre spec}}
+ \Something{filler}
+ \Lbrace \Something{vertical mode material} \Rbrace
+ \Modelist{h, m}
+}}
\bookmark{\tex{vadjust}}
The \type{\vadjust} implementation of \PDFTEX\ adds an optional
-qualifier \Something{pre spec} (which is the string \type{pre}) to
-the original \TEX\ primitive with the same name. As long as there is
-no \type{pre} given, \type{\vadjust} behaves exactly as the original
-(see the \TEX book, p.~281); it appends an adjustment item created
+qualifier \Something{pre spec}, which is simply the string \type{pre}, to
+the original \TEX\ primitive with the same name. If
+no \type{pre} is given, \type{\vadjust} behaves exactly as the original
+(see the \TEX book, p.~281): it appends an adjustment item created
from \Something{vertical mode material} to the current list {\em after}
-the line in which \type{\vadjust} appears. However with the qualifier
+the line in which \type{\vadjust} appears. However, with the qualifier
\type{pre}, the adjustment item is put {\em before} the line in which
\type{\vadjust pre} appears.
@@ -5250,7 +4582,7 @@ to one of the maintainers.
%***********************************************************************
-\section{Additional \PDF\ keys}
+\section[sec.addpdfkeys]{Additional \PDF\ keys}
{\em This section is based on the manual on keys written by Martin
Schr\"oder, one of the maintainers of \PDFTEX.}
@@ -5261,7 +4593,7 @@ to insert additional keys, provided they follow certain rules.
The most important rule is that developers have to register with Adobe
prefixes for the keys they want to insert. Hans Hagen has registered the
-prefix \type {PTEX} for \PDFTEX.
+prefix \type{PTEX} for \PDFTEX.
\PDFTEX\ generates an XObject for every included \PDF. The dictionary of
this object contains these additional keys:
@@ -5292,13 +4624,17 @@ the \PDFReference. The following key ends up in the document catalog.
\NC \bf key \NC \bf type \NC meaning \NC \NR
\HL
\NC PTEX.Fullbanner \NC string \NC The full version of the \pt binary that
-produced the file as displayed by \typ {pdftex --version}, \eg\
+produced the file as displayed by \typ {pdftex -{}-version}, \eg\
{\tt\pdftexbanner}. This is necessary because the string in the
-\type {Producer} key in the info dictionary is rather short,
+\type{Producer} key in the info dictionary is rather short,
namely {\tt pdfTeX-\currentpdftex}. \NC \NR
\HL
\stoptabulate
+Any or all of these keys can be suppressed with the
+\type{\pdfsuppressptexinfo} primitive, described in
+\in{section}[sec.docinfocatalog].
+
%***********************************************************************
\section{Colophon}
@@ -5325,7 +4661,7 @@ texexec --pdfarrange --paper=a5a4 --print=up --addempty=1,2
\stoptyping
Odd and even page sets for non-duplex printers can be generated using
-\type{--pages=odd} and \type{--pages=even} options
+\type{-}\type{-pages=odd} and \type{-}\type{-pages=even} options
(which might require some disciplined shuffling of sheet).
This also demonstrates that \PDFTEX\ can be used for page imposition
@@ -5335,9 +4671,6 @@ purposes (given that \PDFTEX\ and the fonts are set up properly).
\page
-% The next section is sponsored by the paper producing industry -)
-% I will make this proper \quotation's some day
-
\definehead[gnusection][subsection]
\definehead[gnusubject][subsubject]
@@ -5348,7 +4681,7 @@ purposes (given that \PDFTEX\ and the fonts are set up properly).
\section{GNU Free Documentation License}
\startnotmode[screen]
- \switchtobodyfont[4.35pt] % squeeze everything on one page :-}
+ \switchtobodyfont[4.6pt] % squeeze everything on one page :-}
\setuplayout[grid=yes]
\setupcolumns[n=7]
\stopnotmode