path: root/systems/doc/pdftex/manual/pdftex-syntax.txt

%% $Id: syntaxform.pl 742 2016-04-25 17:30:55Z karl $
%% This is the list of new or extended primitives provided by pdftex.
%% Don't edit this file, as it is now auto-generated from the
%% pdfTeX manual source pdftex-t.tex (and the generated
%% pdftex-syntax.tex) by the script syntaxform.awk.
%% Syntax rule conventions borrowed from `TeXbook naruby' by Petr Olsak.

%% Integer registers:
\efcode <font> <8-bit number>                           (integer)
\knaccode <font> <8-bit number>                         (integer)
\knbccode <font> <8-bit number>                         (integer)
\knbscode <font> <8-bit number>                         (integer)
\lpcode <font> <8-bit number>                           (integer)
\pdfadjustinterwordglue                                 (integer)
\pdfadjustspacing                                       (integer)
\pdfappendkern                                          (integer)
\pdfcompresslevel                                       (integer)
\pdfdecimaldigits                                       (integer)
\pdfdraftmode                                           (integer)
\pdfforcepagebox                                        (integer)
\pdfgamma                                               (integer)
\pdfgentounicode                                        (integer)
\pdfimageapplygamma                                     (integer)
\pdfimagegamma                                          (integer)
\pdfimagehicolor                                        (integer)
\pdfimageresolution                                     (integer)
\pdfinclusioncopyfonts                                  (integer)
\pdfinclusionerrorlevel                                 (integer)
\pdfinfoomitdate                                        (integer)
\pdfinfoomitdict                                        (integer)
\pdfmajorversion                                        (integer)
\pdfminorversion                                        (integer)
\pdfobjcompresslevel                                    (integer)
\pdfomitcharset                                         (integer)
\pdfomitprocset                                         (integer)
\pdfoutput                                              (integer)
\pdfpagebox                                             (integer)
\pdfpkresolution                                        (integer)
\pdfprependkern                                         (integer)
\pdfprotrudechars                                       (integer)
\pdfsuppressptexinfo                                    (integer)
\pdfsuppresswarningdupdest                              (integer)
\pdfsuppresswarningdupmap                               (integer)
\pdfsuppresswarningpagegroup                            (integer)
\pdftracingfonts                                        (integer)
\pdfuniqueresname                                       (integer)
\rpcode <font> <8-bit number>                           (integer)
\shbscode <font> <8-bit number>                         (integer)
\showstream                                             (integer)
\stbscode <font> <8-bit number>                         (integer)
\tagcode <font> <8-bit number>                          (integer)
\tracinglostchars                                       (integer)
\tracingstacklevels                                     (integer)

%% Read-only integers:
\pdfelapsedtime                                         (read-only integer)
\pdflastannot                                           (read-only integer)
\pdflastlink                                            (read-only integer)
\pdflastobj                                             (read-only integer)
\pdflastxform                                           (read-only integer)
\pdflastximage                                          (read-only integer)
\pdflastximagecolordepth                                (read-only integer)
\pdflastximagepages                                     (read-only integer)
\pdflastxpos                                            (read-only integer)
\pdflastypos                                            (read-only integer)
\pdfrandomseed                                          (read-only integer)
\pdfretval                                              (read-only integer)
\pdfshellescape                                         (read-only integer)
\pdftexversion                                          (read-only integer)

%% Dimen registers:
\pdfdestmargin                                          (dimen)
\pdfeachlinedepth                                       (dimen)
\pdfeachlineheight                                      (dimen)
\pdffirstlineheight                                     (dimen)
\pdfhorigin                                             (dimen)
\pdfignoreddimen                                        (dimen)
\pdflastlinedepth                                       (dimen)
\pdflinkmargin                                          (dimen)
\pdfpageheight                                          (dimen)
\pdfpagewidth                                           (dimen)
\pdfpxdimen                                             (dimen)
\pdfthreadmargin                                        (dimen)
\pdfvorigin                                             (dimen)

%% Token registers:
\pdfpageattr                                            (tokens)
\pdfpageresources                                       (tokens)
\pdfpagesattr                                           (tokens)
\pdfpkmode                                              (tokens)

%% Expandable commands:
\expanded <tokens>                                      (expandable)
\ifincsname                                             (expandable)
\ifpdfabsdim                                            (expandable)
\ifpdfabsnum                                            (expandable)
\ifpdfprimitive <control sequence>                      (expandable)
\input <general text>                                   (expandable)
\leftmarginkern <box number>                            (expandable)
\pdfcolorstackinit [page] [direct] <general text>       (expandable)
\pdfcreationdate                                        (expandable)
\pdfescapehex <general text>                            (expandable)
\pdfescapename <general text>                           (expandable)
\pdfescapestring <general text>                         (expandable)
\pdffiledump [offset <integer>] [length <integer>] <general text> (expandable)
\pdffilemoddate <general text>                          (expandable)
\pdffilesize <general text>                             (expandable)
\pdffontname <font>                                     (expandable)
\pdffontobjnum <font>                                   (expandable)
\pdffontsize <font>                                     (expandable)
\pdfincludechars <font> <general text>                  (expandable)
\pdfinsertht <integer>                                  (expandable)
\pdflastmatch <integer>                                 (expandable)
\pdfmatch [icase] [subcount <integer>] <general text> <general text> (expandable)
\pdfmdfivesum [file] <general text>                     (expandable)
\pdfnormaldeviate                                       (expandable)
\pdfpageref <page number>                               (expandable)
\pdfstrcmp <general text> <general text>                (expandable)
\pdftexbanner                                           (expandable)
\pdftexrevision                                         (expandable)
\pdfunescapehex <general text>                          (expandable)
\pdfuniformdeviate <number>                             (expandable)
\pdfxformname <object number>                           (expandable)
\pdfximagebbox <integer> <integer>                      (expandable)
\rightmarginkern <box number>                           (expandable)

%% General commands:
\letterspacefont <control sequence> <font> <integer>
\partokenname <control sequence>
\pdfannot <annot type spec>                             (h, v, m)
\pdfcatalog <general text> [openaction <action spec>]
\pdfcolorstack <stack number> <stack action> <general text>
\pdfcopyfont <control sequence> <font>
\pdfdest <dest spec>                                    (h, v, m)
\pdfendlink                                             (h, m)
\pdfendthread                                           (v, m)
\pdffakespace
\pdffontattr <font> <general text>
\pdffontexpand <font> <stretch> <shrink> <step> [autoexpand]
\pdfglyphtounicode <general text> <general text>
\pdfinfo <general text>
\pdfinterwordspaceoff
\pdfinterwordspaceon
\pdfliteral [shipout] [direct | page] <general text>    (h, v, m)
\pdfmapfile <map spec>
\pdfmapline <map spec>
\pdfnames <general text>
\pdfnobuiltintounicode <font>
\pdfnoligatures <font>
\pdfobj <object type spec>                              (h, v, m)
\pdfoutline [<attr spec>] <action spec> [count <integer>] <general text> (h, v, m)
\pdfprimitive <control sequence>
\pdfrefobj <object number>                              (h, v, m)
\pdfrefxform <object number>                            (h, v, m)
\pdfrefximage <object number>
\pdfresettimer
\pdfrestore
\pdfrunninglinkoff
\pdfrunninglinkon
\pdfsave
\pdfsavepos                                             (h, v, m)
\pdfsetmatrix
\pdfsetrandomseed <number>
\pdfspacefont <general text>
\pdfstartlink [<rule spec>] [<attr spec>] <action spec> (h, m)
\pdfthread [<rule spec>] [<attr spec>] <id spec>        (h, v, m)
\pdftrailer <general text>
\pdftrailerid <general text>
\pdftstartthread [<rule spec>] [<attr spec>] <id spec>  (v, m)
\pdfxform [<attr spec>] [<resources spec>] <box number> (h, v, m)
\pdfximage [<rule spec>] [<attr spec>] [<page spec>] [<colorspace spec>] [<pdf box spec>] <general text> (h, v, m)
\quitvmode
\special {pdf: <text> }
\special {pdf:direct: <text> }
\special {pdf:page: <text> }
\special [shipout] {<general text> }
\vadjust [<pre spec>] <filler> { <vertical mode material> } (h, m)

%% Syntax rules:
<general text> --> { <balanced text> }
<attr spec> --> attr <general text>
<resources spec> --> resources <general text>
<rule spec> --> (width | height | depth) <dimen> [<rule spec>]
<object type spec> --> reserveobjnum
                     | [useobjnum <number>] [stream [<attr spec>]] <object contents>
<annot type spec> --> reserveobjnum
                    | [useobjnum <number>] [<rule spec>] <general text>
<object contents> --> <file spec>
                    | <general text>
<xform attr spec> --> [<attr spec>] [<resources spec>]
<image attr spec> --> [<rule spec>] [<attr spec>] [<page spec>] [<colorspace spec>] [<pdf box spec>]
<outline spec> --> [<attr spec>] <action spec> [count <number>] <general text>
<action spec> --> user <user-action spec>
                | goto <goto-action spec>
                | thread <thread-action spec>
<user-action spec> --> <general text>
<goto-action struct spec> --> struct (<numid> | nameid | <general text>)
<goto-action spec> --> [<goto-action struct spec>] <numid>
                     | [<file spec>] [<goto-action struct spec>] <nameid>
                     | [<file spec>] [<goto-action struct spec>] [<page spec>] <general text>
                     | <file spec> [<goto-action struct spec>] <nameid> <newwindow spec>
                     | <file spec> [<goto-action struct spec>] [<page spec>] <general text> <newwindow spec>
<thread-action spec> --> [<file spec>] <numid>
                       | [<file spec>] <nameid>
<colorspace spec> --> colorspace <number>
<pdf box spec> --> mediabox | cropbox | bleedbox | trimbox | artbox
<map spec> --> { [<map modifier>] <balanced text> }
<map modifier> --> + | = | -
<numid> --> num <number>
<nameid> --> name <general text>
<newwindow spec> --> newwindow | nonewwindow
<dest spec> --> [struct <number>] \\
              (<numid> | <nameid>)
              <dest type>
<dest type> --> xyz [zoom <number>]
              | fitr <rule spec>
              | fitbh
              | fitbv
              | fitb
              | fith
              | fitv
              | fit
<thread spec> --> [<rule spec>] [<attr spec>] <id spec>
<id spec> --> <numid> | <nameid>
<file spec> --> file <general text>
<page spec> --> page <number>
<expand spec> --> <stretch> <shrink> <step> [autoexpand]
<stretch> --> <number>
<shrink> --> <number>
<step> --> <number>
<pre spec> --> pre
<pdfspecial spec> --> { [<pdfspecial id> [<pdfspecial modifier>]] <balanced text> }
<pdfspecial id> --> pdf: | PDF:
<pdfspecial modifier> --> direct:
<stack action> --> set | push | pop | current
<goto-action spec> --> [<goto-action struct spec>] <numid>
                     | [<file spec>] [<goto-action struct spec>] <nameid>
                     | [<file spec>] [<goto-action struct spec>] [<page spec>] <general text>
                     | <file spec> [<goto-action struct spec>] <nameid> <newwindow spec>
                     | <file spec> [<goto-action struct spec>] [<page spec>] <general text> <newwindow spec>
<text> }} is equivalent to \Syntax{\pdfliteral
shipout { <text> }}.
================= ERROR
%***********************************************************************
================= ERROR
\subsection{Strings}
================= ERROR
\pdftexprimitive{\Syntax{\pdfescapestring <general text>
                                                        (expandable)}}
\bookmark{\pdfescapestring}
================= ERROR
Starting with version 1.30.0, \PDFTEX\ provides a mechanism for converting
a general text into \PDF\ string. Many characters that may be needed inside
such a text (especially parenthesis), have a special meaning inside a \PDF\
string object and thus, can't be used literally. The primitive replaces each
special \PDF\ character by its literal representation by inserting a backslash
before that character. Some characters (\eg\ space) are also converted into
3-digit octal number. In example, \type{\pdfescapestring{Text (1)}} will be
expanded to \type{Text\040\(1\)}. This ensures a literal interpretation of the
text by the \PDF\ viewer.
\introduced{1.30.0}
================= ERROR
\pdftexprimitive{\Syntax{\pdfescapename <general text>
                                                        (expandable)}}
\bookmark{\pdfescapename}
================= ERROR
In analogy to \type{\pdfescapestring}, \type{\pdfescapename} replaces each
special \PDF\ character inside the general text by its hexadecimal
representation preceded by \type{#} character. This ensures the proper
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}
================= ERROR
\pdftexprimitive{\Syntax{\pdfescapehex <general text>
                                                        (expandable)}}
\bookmark{\pdfescapehex}
================= ERROR
This command converts each character of <general text> into its
hexadecimal representation. Each character of the argument becomes a pair of
hexadecimal digits. \introduced{1.30.0}
================= ERROR
\pdftexprimitive{\Syntax{\pdfunescapehex <general text>
                                                        (expandable)}}
\bookmark{\pdfunescapehex}
================= ERROR
This command treats each character pair of <general text> as
a hexadecimal number and returns an \ASCII\ character of this code.
\introduced{1.30.0}
================= ERROR
\pdftexprimitive{\Syntax{\pdfstrcmp <general text>
                     <general text>                     (expandable)}}
\bookmark{\pdfstrcmp}
================= ERROR
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}
================= ERROR
\pdftexprimitive{\Syntax{\pdfmatch [icase]
                     [subcount <integer>] <general text>
                     <general text>                     (expandable)}}
\bookmark{\pdfmatch}
================= ERROR
This command implements pattern matching (using the syntax of \POSIX\
extended regular expressions). The first <general text> is a
pattern and the second is a string.  The command expands to \type{-1} if
the pattern is invalid, to \type{0} if no match is found, and to
\type{1} if 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 the found (sub)patterns; its default is 10.
\introduced{1.30.0}
================= ERROR
\pdftexprimitive{\Syntax{\pdflastmatch <integer>
                                                        (expandable)}}
\bookmark{\pdflastmatch}
================= ERROR
The matches found with \type{\pdfmatch} are stored in a table. This
command returns the entry for <integer>, in the format
<position>\type{->}<string>; <position> is
the position of the match (starting at zero) or \type{-1} if no match
was found, and <string> is the matched substring.
================= ERROR
Entry~0 contains the match as a whole; the subsequent entries contain
submatches corresponding to the subpatterns, up to \type{subcount-1}.
================= ERROR
If <integer> is less than zero, an error is given.
================= ERROR
For instance:
================= ERROR
\starttyping
\pdfmatch subcount 3 {ab(cd)*ef(gh)(ij)}{abefghij}
\pdflastmatch0 % "0->abefghij"
\pdflastmatch1 % "-1->"
\pdflastmatch2 % "4->gh"
\pdflastmatch3 % "-1->"
\stoptyping
================= ERROR
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}
================= ERROR
%***********************************************************************
================= ERROR
\subsection{Numbers}
================= ERROR
\pdftexprimitive{\Syntax{\ifpdfabsnum                   (expandable)}}
\bookmark{\ifpdfabsnum}
================= ERROR
This conditional works like the standard \type{\ifnum}, except that it
compares absolute values of numbers. Although it seems to be a trivial
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}
================= ERROR
\pdftexprimitive{\Syntax{\ifpdfabsdim                   (expandable)}}
\bookmark{\ifpdfabsdim}
================= ERROR
Analogous to \type{\ifpdfabsnum}, this conditional works like
\type{\ifdim}, except that it compares absolute values of
dimensions. \introduced{1.40.0}
================= ERROR
\pdftexprimitive{\Syntax{\pdfuniformdeviate <number>
                                                        (expandable)}}
\bookmark{\pdfuniformdeviate}
================= ERROR
Generate a uniformly-distributed random integer value between 0
(inclusive) and <number> (exclusive). This primitive expands
to a list of tokens. \introduced{1.30.0}
================= ERROR
\pdftexprimitive{\Syntax{\pdfnormaldeviate              (expandable)}}
\bookmark{\pdfnormaldeviate}
================= ERROR
Generate a normally-distributed random integer with a mean of~0 and
standard deviation 65\,536.  That is, about 68\% of the time, the result
will be between $-65536$ and $65536$ (one standard deviation away from
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}
================= ERROR
\pdftexprimitive{\Syntax{\pdfrandomseed                 (read-only integer)}}
\bookmark{\pdfrandomseed}
================= ERROR
You can use \type{\the\pdfrandomseed} to query the current seed value,
so you can \eg\ write the value to the log file.  The initial value of
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}
================= ERROR
\pdftexprimitive{\Syntax{\pdfsetrandomseed <number>}}
\bookmark{\pdfsetrandomseed}
================= ERROR
Set the random seed (\type{\pdfrandomseed}) to a specific value,
allowing you to replay sequences of semi-randoms at a later moment.
\introduced{1.30.0}
================= ERROR
%***********************************************************************
================= ERROR
\subsection{Timekeeping}
================= ERROR
\pdftexprimitive{\Syntax{\pdfelapsedtime                (read-only integer)}}
\bookmark{\pdfelapsedtime}
================= ERROR
Return a number that represents the time elapsed from the moment of the
start of the run. The elapsed time is returned in `scaled seconds',
meaning seconds divided by 65536, \eg\ \PDFTEX\ has run for
\the\pdfelapsedtime\ `scaled seconds' when this paragraph was
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}
================= ERROR
\pdftexprimitive{\Syntax{\pdfresettimer}}
\bookmark{\pdfresettimer}
================= ERROR
Reset the internal timer so that \type{\pdfelapsedtime}
starts returning micro-time from~0 again. \introduced{1.30.0}
================= ERROR
%***********************************************************************
================= ERROR
\subsection{Files}
================= ERROR
\pdftexprimitive{\Syntax{\pdffilemoddate <general text>
                                                        (expandable)}}
\bookmark{\pdffilemoddate}
================= ERROR
Expands to the modification date of file <general text> in the
same format as for \type{\pdfcreationdate}, \eg\ it's {\tt
\pdffilemoddate {./pdftex-t.tex}} for the source of this manual. As of
version 1.40.20, if the \type{SOURCE_DATE_EPOCH} and
\type{FORCE_SOURCE_DATE} environment variables are both set,
\type{\pdffilemoddate} returns a value in UTC, ending in \type{Z}.
\introduced{1.30.0}
================= ERROR
\pdftexprimitive{\Syntax{\pdffilesize <general text>
                                                        (expandable)}}
\bookmark{\pdffilesize}
================= ERROR
Expands to the size of file <general text>, \eg\ it's {\tt
\pdffilesize {./pdftex-t.tex}} for the source of this manual.
\introduced{1.30.0}
================= ERROR
\pdftexprimitive{\Syntax{\pdfmdfivesum
                     [file]
                     <general text>                     (expandable)}}
\bookmark{\pdfmdfivesum\ file}
================= ERROR
If the keyword \type{file} is given, expands to the \MDFIVE\ of file
\Somethingtext{general text} in uppercase hexadecimal format (same as
\type{\pdfescapehex}). Without \type{file}, expands to the \MDFIVE\ of
the \Somethingtext{generaltext} taken as a string. For example, it's
{\tt \pdfmdfivesum file {./pdftex-t.tex}} for the source of this manual.
\introduced{1.30.0}
================= ERROR
\pdftexprimitive{\Syntax{\pdffiledump
                     [offset <integer>]
                     [length <integer>]
                     <general text>                     (expandable)}}
\bookmark{\pdffiledump}
================= ERROR
Expands to the dump of the first \type{length} \Somethingtext{integer}
bytes of the file \Somethingtext{general text}, in uppercase hexadecimal
format (same as \type{\pdfescapehex}), starting at offset
\type{offset}~\Somethingtext{number}, or the beginning of the file if
\type{offset}. If \type{length} is not given, the default is zero, so
expands to nothing. Both \Somethingtext{integer}s must be $\ge0$. For
example, the first ten bytes of the source of this manual are {\tt
\pdffiledump length 10 {./pdftex-t.tex}}. \introduced{1.30.0}
================= ERROR
\pdftexprimitive{\Syntax{\input <general text>
                                                        (expandable)}}
\bookmark{\input}
================= ERROR
As of \TEXLIVE\ 2020, the \type{\input} primitive in all \TEX\ engines,
including \PDFTEX, now also accepts a group-delimited filename argument,
as a system-dependent extension, as in \type{\input} {
\type{foo.tex} }. The usage of \type{\input} with a standard
space/token-delimited filename is completely unchanged.
================= ERROR
This group-delimited argument was previously implemented in Lua\TEX; now
it is available in all engines. \ASCII\ double quote characters
(\type{"}) are removed from the filename, but it is otherwise left
unchanged after tokenization.
================= ERROR
This extension is unlike most others in that it affects a primitive in
standard \TEX\ (\type{\input}), rather than being related to a new
primitive, command line option, etc. This is allowed because additional
methods of recognizing filenames are explicitly mentioned in
\type{tex.web} as acceptable system-dependent extensions.
================= ERROR
Incidentally, this does not directly affect \LATEX's \type{\input}
command, as that is a macro redefinition of the standard \type{\input}
primitive.
================= ERROR
\introduced{1.40.21}
================= ERROR
%***********************************************************************
================= ERROR
\subsection{Color stack}
================= ERROR
\PDFTEX\ 1.40.0 comes with color stack support (actually any graphic state
stack).
================= ERROR
\pdftexprimitive{\Syntax{\pdfcolorstackinit [page]
                     [direct] <general text>            (expandable)}}
\bookmark{\pdfcolorstackinit}
================= ERROR
The primitive initializes a new graphic stack and returns its number. Optional
page keyword instructs \PDFTEX\ to restore the graphic at the
beginning of every new page. Also optional direct has the same effect
as for \pdfliteral primitive. \introduced{1.40.0}
================= ERROR
\pdftexprimitive{\Syntax{\pdfcolorstack <stack number>
                     <stack action> <general text>}}
\bookmark{\pdfcolorstack}
================= ERROR
The command operates on the stack of a given number. If \Something{stack
action} is push keyword, the new value provided as
<general text> is inserted into the top of the graphic stack
and becomes the current stack value. If followed by pop, the
top value is removed from the stack and the new top value becomes the
current. set keyword replaces the current value with
<general text> without changing the stack size.
current keyword instructs just to use the current stack value
without modifying the stack at all. \introduced{1.40.0}
================= ERROR
%***********************************************************************
================= ERROR
\subsection{Transformations}
================= ERROR
Since the content of \pdfliteral is not interpreted anyhow, any
transformation inserted directly into the content stream, as well as saving
and restoring the current transformation matrix, remains unnoticed by
\PDFTEX\ positioning mechanism. As a consequence, links and other annotations
(that are formed in \PDF\ as different layer then the page content) are not
affected by such user-defined transformations. \PDFTEX\ 1.40.0 solves this
problem with three new primitives.
================= ERROR
\pdftexprimitive{\Syntax{\pdfsetmatrix}}
\bookmark{\pdfsetmatrix}
================= ERROR
Afine transformations are normally expressed with six numbers. First
four (no unit) values defining scaling, rotating and skewing, plus two
extra dimensions for shifting. Since the translation is handled by \TeX\
itself, \pdfsetmatrix primitive expects as an argument a string
containing just the first four numbers of the transformation separated
by a space and assumes two position coordinates to be~0. In example,
\type{\pdfsetmatrix{0.87 -0.5 0.5 0.87}} rotates the current space by 30
degrees, inserting \type{0.87 -0.5 0.5 0.87 0 0 cm} into the content
stream. \introduced{1.40.0}
================= ERROR
\pdftexprimitive{\Syntax{\pdfsave}}
\bookmark{\pdfsave}
================= ERROR
The command saves the current transformation by inserting \type{q}
operator into the content stream. \introduced{1.40.0}
================= ERROR
\pdftexprimitive{\Syntax{\pdfrestore}}
\bookmark{\pdfrestore}
================= ERROR
The command restores previously saved transformation by inserting \type{Q}
operator into the content stream. One should keep in mind that \pdfsave
and \pdfrestore pairs should always be properly nested and should start
and end at the same group level. \introduced{1.40.0}
================= ERROR
%***********************************************************************
================= ERROR
\subsection{Macro programming}
================= ERROR
Expansion-related.
================= ERROR
\pdftexprimitive{\Syntax{\expanded <tokens>
                                                        (expandable)}}
\bookmark{\expanded}
================= ERROR
Expands <tokens> in exactly the same way as \type{\message}.
In contrast to \type{\edef}, macro parameter characters do not need to
be doubled. \type{\protected} macros are not expanded.
\introduced{1.40.20}
================= ERROR
================= ERROR
\pdftexprimitive{\Syntax{\ifincsname                    (expandable)}}
\bookmark{\ifincsname}
================= ERROR
This conditional is true if evaluated inside \type{\csname ... \endcsname},
and false otherwise.
================= ERROR
================= ERROR
\pdftexprimitive{\Syntax{\ifpdfprimitive <control sequence>
                                                        (expandable)}}
\bookmark{\ifpdfprimitive}
================= ERROR
This condition checks if the following control sequence has its
primitive meaning. If it has, \type{\ifpdfprimitive} returns true. In
any other case (redefined, made \type{\undefined}, has never been
primitive) false is returned.  \introduced{1.40.0}
================= ERROR
================= ERROR
flapping\pdftexprimitive{\Syntax{\partokencontext <number>}}
\bookmark{\partokencontext}
================= ERROR
The {\em par-token} (i.e., the token with the name given by
\type{\partokenname}, or \type{\par} by default; see
\type{\partokenname}, next) is inserted into the input stream in
different places, according to the \type{\partokencontext} value. This
value can be:
================= ERROR
0: {\em par-token} is inserted at empty lines (more exactly, when a
                     token category~5 is seen in state~$N$, reading a line); before
                     \type{\end}, \type{\vskip}, \type{\hrule}, \type{\unvbox}, and
                     \type{\halign}, if \TeX{} is in horizontal mode when those commands
                     are seen; and in various error recovery situations. These are the
                     standard cases, and this is the default value.
================= ERROR
1: {\em par-token} is inserted as above, and also at the end of
                     \type{\vbox}, \type{\vtop}, and \type{\vcenter}, if \TeX{} is in
                     horizontal mode at the time.
================= ERROR
2: {\em par-token} is inserted as above, and also at the end of
                     \type{\insert}, \type{\vadjust}, \type{\output}, \type{\noalign}, and
                     items of \type{\valign}, again if \TeX{} is in horizontal mode at the
                     time.
================= ERROR
With the default \type{\partokencontext=0}, \TEX\ behaves in its normal
way: the situations in cases 1 and 2 are processed by a direct call of
{\em end-paragraph} routine, with no emitted {\em par-token}.
================= ERROR
If \type{\partokencontext=1} then \TeX\ inserts the {\em par-token} in
additional cases: when vertical boxes are completed but horizontal mode
is not finished. Since vboxes are not uncommonly inserted directly by
users, with horizontal mode material, this allows macro programmers to
control all such boxes being finished by a {\em par-token}. An example:
================= ERROR
\starttyping
\partokenname\_mypar
\partokencontext=1
\def\_mypar{Hi there!\endgraf}
\vbox{Vbox text.}
\stoptyping
================= ERROR
This will output ``\type{Hi there!''}\ after ``\type{Vbox text.}''.
================= ERROR
Finally, with \type{\partokencontext=2}, all cases where classical \TeX\
uses the direct {\em end-paragraph} routine are changed to emit the {\em
par-token} instead. In contrast to case~1, these commands are rarely
invoked directly by users with horizontal mode material.
================= ERROR
The setting of the register \type{\partokencontext} is local.
\introduced{1.40.24}
================= ERROR
\pdftexprimitive{\Syntax{\partokenname <control sequence>}}
\bookmark{\partokenname}
================= ERROR
\TeX{} internally inserts a control sequence, named \type{\par} by
default, into the input stream at empty lines, the end of vboxes, and
various other places (see \type{\partokencontext}, above). Let's call this
control sequence the {\em par-token}.
================= ERROR
Executing \type{\partokenname}<control-sequence> changes the
name of the {\em par-token} from \type{\par} to the given
<control-sequence>. The setting performed by
\type{\partokenname} is global.
================= ERROR
This makes it possible to release the name \type{\par} to the ``user's
name space'', i.e., after \type{\partokenname}, users can define and use
\type{\par} as they wish without changing the behavior of anything
internal to \TeX{}. For example:
================= ERROR
\starttyping
\catcode`\_=11
\partokenname\_mypar % use \_mypar at user level
\let\_mypar=\par     % make \_mypar equivalent to built-in \par
\def\par{some random text} % redefine \par
Hello world.
================= ERROR
Goodbye.
\end
\stoptyping
================= ERROR
This will not output ``\type{some random text}'' (the definition of
\type{\par}), due to the \type{\partokenname} setting.
================= ERROR
By default, the meaning of the {\em par-token} is to end a paragraph
(also named as \type{\endgraf} in the plain \TEX\ format). It can be
changed as usual with, for example, \type{\def}. Naturally, it is the
control sequence name given to \type{\partokenname} that must be
redefined. Continuing the previous example (prior to the \type{\end}):
================= ERROR
\starttyping
\def\_mypar{Hi there!\endgraf}
Paragraph one.
================= ERROR
Paragraph two.\let\_mypar=\endgraf
\stoptyping
================= ERROR
This will output ``\type{Hi there!''}\ after ``\type{Paragraph one.}'',
before ending the paragraph.
================= ERROR
Another behavior of the {\em par-token} built into \TEX\ is that macros
not defined as \type{\long} cause the error ``runaway argument'' if the
{\em par-token} is scanned as a parameter. After
\type{\setpartokenname}, it will be the new control sequence name that
triggers this error, not \type{\par}. For example (still continuing the
same example):
================= ERROR
\starttyping
\def\amac#1{}
\amac{long test, no error: \par}
\amac{long test, gives error: \_mypar}
\stoptyping
================= ERROR
\introduced{1.40.24}
================= ERROR
\pdftexprimitive{\Syntax{\pdfprimitive <control sequence>}}
\bookmark{\pdfprimitive}
================= ERROR
This command executes the primitive meaning of the following control
sequence, regardless of whether the control sequence has been redefined
or made undefined. If the primitive was expandable, \type{\pdfprimitive}
expands also. On the other hand, if the following control sequence never
was a primitive, nothing happens and no error is raised. (In some
versions of \PDFTEX\ prior to 1.40.19, an error was wrongly given.)
\introduced{1.40.0}
================= ERROR
%***********************************************************************
================= ERROR
\subsection{Typesetting}
================= ERROR
\pdftexprimitive{\Syntax{\pdfinsertht <integer>
                                                        (expandable)}}
\bookmark{\pdfinsertht}
================= ERROR
If <integer> is the number of an insertion class, this command
returns the height of the corresponding box at the current time.
For instance, the following returns \type{12pt} in plain \TEX:
================= ERROR
\starttyping
Abc\footnote*{Whatever.}\par
\pdfinsertht\footins
\stoptyping
================= ERROR
================= ERROR
\pdftexprimitive{\Syntax{\pdflastxpos                   (read-only integer)}}
\bookmark{\pdflastxpos}
================= ERROR
This primitive returns an integer number representing the absolute $x$
coordinate of the last point marked by \type{\pdfsavepos}. The unit is
`scaled points' (sp).
================= ERROR
================= ERROR
\pdftexprimitive{\Syntax{\pdflastypos                   (read-only integer)}}
\bookmark{\pdflastypos}
================= ERROR
Completely analogous to \type{\pdflastxpos}, returning the $y$ coordinate.
================= ERROR
================= ERROR
\pdftexprimitive{\Syntax{\pdfsavepos                    (h, v, m)}}
\bookmark{\pdfsavepos}
================= ERROR
This primitive marks the current absolute ($x,y$) position on the
media, with the reference point in the lower left corner. It is active
only during page shipout, when the page is finally assembled. The
position coordinates can then be retrieved by the \type{\pdflastxpos}
and \type{\pdflastypos} primitives, and \eg\ written out to some
auxiliary file. The coordinates can be used only after the current
\type{\shipout} has been finalized, therefore normally two \PDFTEX\
runs are required to utilize these primitives. Starting with
\PDFTEX\ 1.40.0, this mechanism can be used also while running
in \DVI\ mode.
================= ERROR
================= ERROR
\pdftexprimitive{\Syntax{\quitvmode}}
\bookmark{\quitvmode}
================= ERROR
The primitive instructs \PDFTEX\ to quit vertical mode and start
typesetting a paragraph. Thus, \type{\quitvmode} has the same basic
effect as the \type{\leavevmode} macro from \type{plain.tex}. However,
\type{\leavevmode} expands the \type{\everypar} tokens list, which may
or may not be desired. \type{\quitvmode} does not expand
\type{\everypar}. \introduced{1.21a}
================= ERROR
================= ERROR
\pdftexprimitive{\Syntax{\vadjust
                     [<pre spec>]
                     <filler>
                     { <vertical mode material> }
                                                        (h, m)