From c98571489bb4ffe9f8d094f7e14e8fa81ba15c1d Mon Sep 17 00:00:00 2001
From: Karl Berry <karl@freefriends.org>
Date: Mon, 16 Jun 2008 18:32:50 +0000
Subject: move to texmf-dist a la luatex, since this doc is
 distribution-independent (heiko 15 Jun 2008 07:59:53)

git-svn-id: svn://tug.org/texlive/trunk@8788 c570f23f-e606-0410-a88d-b1316a301751
---
 Master/texmf-dist/doc/pdftex/manual/pdftex-t.tex | 5228 ++++++++++++++++++++++
 1 file changed, 5228 insertions(+)
 create mode 100644 Master/texmf-dist/doc/pdftex/manual/pdftex-t.tex

(limited to 'Master/texmf-dist/doc/pdftex/manual/pdftex-t.tex')

diff --git a/Master/texmf-dist/doc/pdftex/manual/pdftex-t.tex b/Master/texmf-dist/doc/pdftex/manual/pdftex-t.tex
new file mode 100644
index 00000000000..08d41e4414d
--- /dev/null
+++ b/Master/texmf-dist/doc/pdftex/manual/pdftex-t.tex
@@ -0,0 +1,5228 @@
+% interface=english modes=letter,screen output=pdftex
+% vim: tw=79
+
+% $Id: pdftex-t.tex,v 1.675 2007/01/25 10:37:13 hhenkel Exp $
+
+% The number of lines on the titlepage depends on the kind of
+% \PDF\ code that \PDFTEX\ generates.
+
+\setvariables[pdftex][titlepagelines=55] % 55 should be ok for non-rc* version
+
+%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
+%D texexec --result=pdftex-a.pdf pdftex-t
+%D
+%D Letter size manual:
+%D
+%D texexec --mode=letter --result=pdftex-l.pdf pdftex-t
+%D
+%D Booklet (given that A4 document is available):
+%D
+%D texexec --pdfarrange --paper=a5a4 --print=up --addempty=1,2 --result=pdftex-b.pdf pdftex-a
+%D
+%D Screen version
+%D
+%D texexec --mode=screen pdftex-t
+
+%D This is the \PDFTEX\ manual, so it makes sense to force \PDF\ output here.
+
+\setupoutput
+  [pdftex]
+
+%D ConTeXt defaults to 1.5; we want to be backwards compatible (and we don't
+%D use any features from 1.4++ anyway, do we?)
+\pdfminorversion=3
+
+%D First we define ourselves some abbreviations, if only to force
+%D consistency and to save typing. We use real small capitals, not pseudo
+%D ones.
+
+\setupsynonyms
+  [abbreviation]
+  [textstyle=smallcaps,
+   style=smallcaps,
+   location=left,
+   width=broad,
+   sample=\POSTSCRIPT]
+
+\setupcapitals
+  [title=no]
+
+\def\rcsscan $#1 #2,v #3 #4/#5/#6 #7${
+  \def\rcsrevision{#3}
+  \def\rcsyear{#4}
+  \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}
+}
+
+\rcsscan $Id: pdftex-t.tex,v 1.675 2007/01/25 10:37:13 hhenkel Exp $
+
+\def\currentpdftex{1.40.0}
+
+%***********************************************************************
+
+\def\eTeX{{$\varepsilon$}-\kern-.125em\TeX}
+\def\eg{e.\,g.}
+\def\Eg{E.\,g.}
+\def\PDFReference{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 [CMACTEX]    {CMac\TeX}   {\MAC\ \WEBC\ distribution}
+\abbreviation [CONTEXT]    {\ConTeXt}   {general purpose macro package}
+\abbreviation [CTAN]       {CTAN}       {global \TEX\ archive server}
+%\abbreviation [DJGPP]      {djgpp}      {DJ Delorie's \GNU\ Programming Platform}
+\abbreviation [DVI]        {dvi}        {native \TEX\ Device Independent file format}
+\abbreviation [ENCTEX]     {enc\TeX}    {enc\TeX\ extension to \TEX}
+\abbreviation [EPSTOPDF]   {epstopdf}   {\EPS\ to \PDF\ conversion tool}
+\abbreviation [EPS]        {eps}        {Encapsulated PostScript}
+\abbreviation [ETEX]       {\eTeX}      {an extension to \TEX}
+\abbreviation [EXIF]       {exif}       {Exchangeable Image File format (JPEG file variant)}
+\abbreviation [FPTEX]      {fp\TeX}     {\WIN\ \WEBC\ distribution}
+\abbreviation [GHOSTSCRIPT] {Ghostscript} {\PS\ and \PDF\ language interpreter}
+\abbreviation [GNU]        {gnu}        {GNU's Not Unix}
+\abbreviation [HZ]         {hz}         {Hermann Zapf optimization}
+\abbreviation [JBIG]       {jbig}       {Joint Bi-level Image Experts Group}
+\abbreviation [JBIGTWO]    {jbig2}      {Joint Bi-level Image Experts Group}
+\abbreviation [JPEG]       {jpeg}       {Joint Photographic Experts Group}
+\abbreviation [LATEX]      {\LaTeX}     {general purpose macro package}
+\abbreviation [MAC]        {Macintosh}  {Macintosh hardware platform}
+\abbreviation [MACOSX]     {Mac\,OS\,X} {Macintosh operating system version 10}
+\abbreviation [MDFIVE]     {md5}        {MD5 message-digest algorithm}
+\abbreviation [METAFONT]   {\MetaFont}  {graphic programming environment, bitmap output}
+\abbreviation [METAPOST]   {\MetaPost}  {graphic programming environment, vector output}
+\abbreviation [MIKTEX]     {MikTeX}     {\WIN\ distribution}
+\abbreviation [MLTEX]      {ML\TeX}     {ML\TeX\ extension to \TEX}
+\abbreviation [MPTOPDF]    {mptopdf}    {\METAPOST\ to \PDF\ conversion tool}
+\abbreviation [MSDOS]      {MSDos}      {Microsoft DOS platform (Intel)}
+\abbreviation [PDFETEX]    {pdfe\TeX}   {\ETEX\ extension producing \PDF\ output}
+\abbreviation [PDFLATEX]   {pdf\LaTeX}  {\TEX\ extension producing \PDF\ output (\LATEX\ format loaded)}
+\abbreviation [PDFTEX]     {pdf\TeX}    {\TEX\ extension producing \PDF\ output}
+\abbreviation [PDF]        {pdf}        {Portable Document Format}
+\abbreviation [PERL]       {Perl}       {Perl programming environment}
+\abbreviation [PFA]        {PFA}        {Adobe PostScript Font format (ASCII)}
+\abbreviation [PFB]        {PFB}        {Adobe PostScript Font format (Binary)}
+\abbreviation [PGC]        {pgc}        {\PDF\ Glyph Container}
+\abbreviation [PK]         {pk}         {Packed bitmap font}
+\abbreviation [PNG]        {png}        {Portable Network Graphics}
+\abbreviation [PROTEXT]    {pro\TeX t}  {\WIN\ \WEBC\ distribution based on \MIKTEX}
+\abbreviation [PS]         {ps}         {PostScript}
+\abbreviation [POSTSCRIPT] {PostScript} {PostScript}
+\abbreviation [PSTOPDF]    {PStoPDF}    {PostScript to \PDF\ converter (on top of GhostScript)}
+\abbreviation [RGB]        {rgb}        {Red Green Blue color specification}
+\abbreviation [TCX]        {tcx}        {\TEX\ Character Translation}
+\abbreviation [TDS]        {tds}        {\TEX\ Directory Standard}
+\abbreviation [TETEX]      {te\TeX}     {\TEX\ distribution for \UNIX\ (based on \WEBC)}
+\abbreviation [TEXEXEC]    {\TeX exec}  {\CONTEXT\ command line interface}
+\abbreviation [TEXINFO]    {Texinfo}    {generate typeset documentation from info pages}
+\abbreviation [TEXUTIL]    {\TeX util}  {\CONTEXT\ utility tool}
+\abbreviation [TEX]        {\TeX}       {typographic language and program}
+\abbreviation [TEXLIVE]    {\TeX\ Live} {\TeX-Live distribution (multiple platform)}
+\abbreviation [TFM]        {tfm}        {\TEX\ Font Metrics}
+\abbreviation [TIF]        {tiff}       {Tagged Interchange File format}
+\abbreviation [TUG]        {tug}        {\TEX\ Users Group}
+\abbreviation [UNIX]       {Unix}       {Unix platform}
+\abbreviation [URL]        {url}        {Uniform Resource Locator}
+\abbreviation [WEBC]       {Web2c}      {official multi||platform \WEB\ environment}
+\abbreviation [WEB]        {web}        {literate programming environment}
+\abbreviation [WIN]        {Win32}      {Microsoft Windows platform}
+\abbreviation [XEMTEX]     {XEm\TeX}    {\WIN\ \WEBC\ distribution}
+\abbreviation [ZIP]        {zip}        {compressed file format}
+
+%D It makes sense to predefine the name of the author of \PDFTEX, doesn't it?
+
+\def\THANH{H\`an Th\^e\llap{\raise 0.5ex\hbox{\'{}}} Th\`anh}
+
+%D Because they are subjected to changes and spoil the visual appearance of
+%D the \TEX\ source, \URL's are defined here.
+
+\useURL [ptex_org]      [http://www.pdftex.org] % links to ptex_examples
+\useURL [ptex_ctan]     [ctan:systems/pdftex]
+%\useURL [ptex_devel]    [http://pdftex.sarovar.org/current/]
+\useURL [ptex_sarovar]  [http://sarovar.org/projects/pdftex/]
+%\useURL [ptex_examples] [http://www.tug.org/applications/pdftex/]
+\useURL [tex_showcase]  [http://www.tug.org/texshowcase]
+
+\useURL [tetex]         [http://www.tug.org/teTeX/]
+\useURL [texlive]       [http://www.tug.org/tex-live/]
+\useURL [ctan_systems]  [ctan:systems]
+\useURL [win32]         [ctan:systems/win32]
+%\useURL [amiga]         [ctan:systems/amiga/amiweb2c/]
+
+\useURL [fabrice]    [mailto:popineau@supelec.fr]
+\useURL [thomas]     [mailto:te@dbs.uni-hannover.de]
+\useURL [andreas]    [mailto:andreas.scherer@pobox.com]
+\useURL [christian]  [mailto:cschenk@berlin.snafu.de]
+\useURL [context]    [http://www.pragma-ade.com]
+\useURL [pdfreference] [http://www.adobe.com/devnet/pdf/pdf_reference.html]
+
+% where the bug reports should go:
+\useURL [ptex_bugs]  [mailto:pdftex@tug.org]                                  [] [pdftex@tug.org]
+% anything else pdftex related:
+\useURL [ptex_list]  [mailto:pdftex@tug.org]                                  [] [pdftex@tug.org]
+
+\useURL [sebastian]  [mailto:s.rahtz@elsevier.co.uk]                          [] [s.rahtz@elsevier.co.uk]
+\useURL [sebastian]  [mailto:sebastian.rahtz@computing-services.oxford.ac.uk] [] [sebastian.rahtz@computing-services.oxford.ac.uk]
+\useURL [thanh]      [mailto:thanh@informatics.muni.cz]                       [] [thanh@informatics.muni.cz]
+\useURL [thanh]      [mailto:hanthethanh@myrealbox.com]                       [] [hanthethanh@myrealbox.com]
+\useURL [martin]     [mailto:martin@pdftex.org]                               [] [martin@pdftex.org]
+\useURL [hans]       [mailto:pragma@wxs.nl]                                   [] [pragma@wxs.nl]
+\useURL [hartmut]    [mailto:hartmut_henkel@gmx.de]                           [] [hartmut\_henkel@gmx.de]
+\useURL [pawel]      [mailto:p.jackowski@gust.org.pl]                         [] [p.jackowski@gust.org.pl]
+
+%D The primitive definitions are specified a bit fuzzy using the next set of
+%D commands. Some day I'll write some proper macros to deal with this.
+
+% keep next 2 lines as temporary kludge for a while to make \type{} of
+% older ConTeXt versions handle these two new primitives; the original
+% problem with \type{} is already solved in ConTeXt as of 2006-02-14.
+\let\ifpdfabsnum\relax
+\let\ifpdfabsdim\relax
+
+\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\Means      {\Sugar{\mathematics{\rightarrow}}}
+\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}}}
+
+% introduced
+\def\introduced#1{The primitive has been introduced in \PDFTEX\ #1.}
+
+% to get bookmarks for primitives like \ifpdfprimitive
+\appendtoks\def\tex#1{\string\\#1}\to\simplifiedcommands
+
+%D We typeset the \URL's in a monospaced font.
+
+\setupurl
+  [style=type]
+
+%D The basic layout is pretty simple. Because we want non european readers to
+%D read the whole text as well, a letter size based alternative is offered
+%D too. Mode switching is taken care of at the command line when running
+%D \TEXEXEC.
+
+\startmode[letter]
+
+  \setuppapersize
+    [letter][letter]
+
+\stopmode
+
+\setuplayout
+  [topspace=1.5cm,
+   backspace=2.5cm,
+   leftmargin=2.5cm,
+   width=middle,
+   footer=1.5cm,
+   header=1.5cm,
+   height=middle]
+
+%D For the moment we use the description mechanism to typeset keywords etc.
+%D Well, I should have used capitals.
+
+\definedescription
+  [description]
+  [location=serried,
+   width=broad]
+
+\definedescription
+  [PathDescription]
+  [location=left,
+   sample=TEXPSHEADERS,
+   width=broad,
+   headstyle=type]
+
+\definehead
+  [pdftexprimitive]
+  [subsubsection]
+
+\setuphead
+  [pdftexprimitive]
+  [style=,
+   before=\blank,
+   after=\blank,
+   numbercommand=\SubSub]
+
+%D This is typically a document where we want to save pages,
+%D so we don't start any matter (part) on a new page.
+
+\setupsectionblock [frontpart] [page=]
+\setupsectionblock [bodypart]  [page=]
+\setupsectionblock [backpart]  [page=]
+
+%D The \type{\SubSub} command is rather simple and generates a triangle.
+%D This makes the primitives stand out a bit more.
+
+\def\SubSub#1{\mathematics{\blacktriangleright}}
+
+%D But, for non Lucida users, the next one is more safe:
+
+\def\SubSub#1{\goforwardcharacter}
+
+%D I could have said:
+%D
+%D \starttyping
+%D \setupsection[section-5][previousnumber=no,bodypartconversion=empty]
+%D \setuplabeltext[subsubsection=\mathematics{\blacktriangleright}]
+%D \stoptyping
+%D
+%D but this is less clear.
+
+%D We use white space, but not too much.
+
+\setupwhitespace
+  [medium]
+
+\setupblank
+  [medium]
+
+%D Verbatim things get a small margin.
+
+\setuptyping
+  [margin=standard]
+
+\definetyping
+  [esctyping]
+\setuptyping
+  [esctyping]
+  [margin=standard,option=commands,escape=@]
+
+%D Due to the lots of verbatim we will be a bit more tolerant in breaking
+%D paragraphs into lines.
+
+\setuptolerance
+  [verytolerant,stretch]
+
+%D We put the chapter and section numbers in the margin and use bold fonts.
+
+\setupheads
+  [alternative=margin]
+
+\setuphead
+  [section]
+  [style=\bfb]
+
+\setuphead
+  [subsection]
+  [style=\bfa]
+
+%D The small table of contents is limited to section titles and is fully
+%D interactive.
+
+\setuplist
+  [section]
+  [criterium=all,
+   interaction=all,
+   width=2em,
+   aligntitle=yes,
+   alternative=a]
+
+%D Ah, this manual is in english!
+
+\mainlanguage
+  [en]
+
+%D We use Palatino fonts, because they look so well on the screen. The
+%D version generated at \PRAGMA\ uses Optima Nova instead. Both fonts are
+%D designed by Hermann Zapf.
+
+\setupfonthandling [hz] [min=25,max=25,step=5]
+
+\setupalign
+  [hz,hanging]
+
+\startnotmode[atpragma]
+
+  \setupfontsynonym [Serif]            [handling=quality]
+  \setupfontsynonym [SerifBold]        [handling=quality]
+  \setupfontsynonym [SerifSlanted]     [handling=quality]
+  \setupfontsynonym [SerifItalic]      [handling=quality]
+  \setupfontsynonym [SerifBoldSlanted] [handling=quality]
+  \setupfontsynonym [SerifBoldItalic]  [handling=quality]
+
+  %setupfontsynonym [Mono]             [handling=quality] % sloooow
+
+  % We use adobe metrics instead of urw metrics because tetex only
+  % ships the former. Beware, these metrics differ!
+
+  \loadmapfile[context-base.map]
+  \usetypescript [adobekb] [\defaultencoding]
+  \usetypescript [palatino][\defaultencoding]
+
+  \setupbodyfont
+    [palatino,10pt]
+
+  \definefontsynonym[TitleFont][SerifBold]
+
+\stopnotmode
+
+\startmode[atpragma]
+
+  \usetypescriptfile[type-ghz]
+
+  \setupfontsynonym [Sans]            [handling=quality]
+  \setupfontsynonym [SansBold]        [handling=quality]
+  \setupfontsynonym [SansSlanted]     [handling=quality]
+  \setupfontsynonym [SansItalic]      [handling=quality]
+  \setupfontsynonym [SansBoldSlanted] [handling=quality]
+  \setupfontsynonym [SansBoldItalic]  [handling=quality]
+
+  %setupfontsynonym [Mono]             [handling=quality] % sloooow
+
+  \definetypeface[optima][ss][sans][optima-nova] [default][encoding=\defaultencoding]
+  \definetypeface[optima][tt][mono][latin-modern][default][encoding=\defaultencoding,rscale=1.1]
+
+  \setupbodyfont[optima,10pt,ss]
+
+  \definefontsynonym[TitleFont][SansBold]
+
+\stopmode
+
+%D This document is mildly interactive. Yes, Thanh's name will end up ok in
+%D the document information data.
+
+\setupinteraction
+  [state=start,
+   style=normal,
+   color=,
+   page=yes,
+   openaction=firstpage,
+   title=the pdfTeX users manual,
+   author={H\`an Th\^e Th\`anh, Sebastian Rahtz, Hans Hagen, Hartmut Henkel,
+   Pawe\l\ Jackowski, Martin Schröder}]
+
+\setupinteractionscreen % still needed?
+
+\startnotmode[screen]
+
+\setupinteractionscreen
+  [option=bookmark]
+
+\stopnotmode
+
+%D Some headers and footers will complete the layout.
+
+\setupheadertexts
+  [The pdf\TeX\ user manual]
+
+\setupfootertexts
+  [pagenumber]
+
+%D For Tobias Burnus, who loves bookmarks, I've enabled them.
+
+\placebookmarks
+  [section,subsection,pdftexprimitive]
+
+%D Let's also define a screen layout:
+
+\startmode[screen] \environment pdftex-i \stopmode
+
+%D We auto-cross link the paper and screen version:
+
+\startnotmode[screen]
+
+%\coupledocument
+%  [screenversion]
+%  [pdftex-s]
+%  [section,subsection,subsubsection,pdftexprimitive]
+%  [the screen version]
+
+\setuphead
+  [section,subsection,subsubsection,pdftexprimitive]
+  [file=screenversion]
+
+\setuplist
+  [section]
+  [alternative=c]
+
+\stopnotmode
+
+%D The text starts here!
+
+\starttext
+
+%D Being lazy, I don't split the file, so paper and screen get
+%D mixed in one document.
+
+\startmode[screen] \getbuffer[screen] \stopmode
+
+\startnotmode[screen]
+
+%D But first we typeset the title page. It has a background. This
+%D background, showing a piece of \PDF\ code, will be referred to
+%D later on.
+
+%D We can use more modern \CONTEXT\ features, but for the moment
+%D stick to the old style and methods.
+
+\NormalizeFontWidth
+  \TitleFont
+  {\hskip.5mm The pdf\TeX\ user manual} % \hskip is fake offset
+  \paperheight
+  {TitleFont}
+
+\setupbackgrounds
+  [page]
+  [background={title,joke,names,content}]
+
+\defineoverlay
+  [title]
+  [\hbox to \paperwidth
+     {\hfill
+      \TitleFont\setstrut
+      \rotate{The pdf\TeX\ user manual}%
+      \hskip.5cm}] % \dp\strutbox}]
+
+% \defineoverlay
+%   [joke]
+%   [\hbox to \paperwidth
+%      {\TitleFont\setstrut
+%       \dimen0=\overlaywidth
+%       \advance\dimen0 by -\ht\strutbox
+%       \advance\dimen0 by -\dp\strutbox
+%       \advance\dimen0 by -1cm
+%       \dimen2=\overlayheight
+%       \advance\dimen2 by -1cm
+%       \hskip.5cm\expanded{\externalfigure
+%          [pdftex-z.pdf]
+%          [width=\the\dimen0,height=\the\dimen2]}%
+%       \hfill}]
+
+% \defineoverlay
+%   [names]
+%   [\vbox to \paperheight
+%      {\dontcomplain
+%       \TitleFont\setstrut
+%       \setbox0=\hbox{\TeX}%
+%       \hsize\paperwidth
+%       \rightskip\ht0
+%       \advance\rightskip\dp\strutbox
+%       \advance\rightskip\dp\strutbox
+%       \bfa \setupinterlinespace
+%       \vfill
+%       \hfill \THANH \endgraf
+%       \hfill Sebastian Rahtz \endgraf
+%       \hfill Hans Hagen
+%       \hfill Hartmut Henkel
+%       \hfill Pawe\l\ Jackowski
+%       \vskip 1ex
+%       \hfill \currentdate
+%       \vskip 2ex}]
+
+\defineoverlay
+  [content]
+  [\overlaybutton{contents}]
+
+% title page
+
+\definelayout
+  [titlepage]
+  [backspace=.5cm,
+   cutspace=3.5cm,
+   topspace=.5cm,
+   bottomspace=.5cm,
+   header=0pt,
+   footer=0pt,
+   lines=\getvariable{pdftex}{titlepagelines},
+   grid=yes,
+   width=middle]
+
+\definecolumnset
+  [titlepage]
+  [n=2,distance=0.2cm]
+
+\start
+
+    \chardef\fontdigits=2
+    \switchtobodyfont[12pt,tt]
+    \setupinterlinespace[line=\dimexpr((\paperheight-1cm)/\getvariable{pdftex}{titlepagelines})]
+    \setuptyping[margin=,color=]
+    \setuplayout[titlepage]
+
+    \startcolumnset[titlepage]
+      \typefile{pdftex-t.txt}
+    \stopcolumnset
+
+    \page
+    \setuplayout
+
+\stop
+
+% \startstandardmakeup
+%
+% %D The titlepage is generated using the background overlay mechanism. This
+% %D saves me the trouble of determining funny skips and alignments. So no text
+% %D goes here.
+%
+% \stopstandardmakeup
+
+\setupbackgrounds
+  [page]
+  [background=]
+
+%D The inside title page is as follows.
+
+\startstandardmakeup[footerstate=none]
+
+  \dontcomplain
+
+  \setupalign[left]
+
+  \start
+
+    \bfd The pdf\TeX\ user manual
+
+    \bfa \setupinterlinespace
+
+    \vskip4ex
+
+    \THANH\par
+    Sebastian Rahtz\par
+    Hans Hagen\par
+    Hartmut Henkel\par
+    Pawe\l\ Jackowski\par
+    Martin Schr\"oder\par
+
+    \vskip3ex
+
+    \rcsmonthname\ \rcsday, \rcsyear\par
+    \vskip1ex
+    Rev.\ \rcsrevision
+
+  \stop
+
+  \vfill
+
+  \startlines
+    The title page of this manual
+    represents the plain \TeX\ coded
+    text ``Welcome to pdf\TeX !''
+  \stoplines
+
+  \blank[2*big] \setuptyping[after=]
+
+  \starttyping
+    \pdfoutput=1
+    \pdfcompresslevel=0
+    \font\tenrm=ptmr8r
+    \tenrm
+    Welcome to pdf\TeX!
+    \bye
+  \stoptyping
+
+\stopstandardmakeup
+
+\setuppagenumber[number=1] % added in case of single sided usage
+
+%D So far for non screen mode.
+
+\stopnotmode
+
+%D We start with a small table of contents, typeset in double column format.
+
+\startfrontmatter
+
+\subject[contents]{Contents}
+
+\startcolumns[distance=3em]
+  \placelist[section]
+\stopcolumns
+
+\stopfrontmatter
+
+%D And here it is: the main piece of text.
+
+\startbodymatter
+
+%***********************************************************************
+
+\section{Introduction}
+
+The main purpose of the \PDFTEX\ project is to create and maintain
+an extension of \TEX\ that can produce \PDF\ directly from \TEX\
+source files and improve|/|enhance the result of \TEX\ typesetting
+with the help of \PDF. When \PDF\ output is not selected, \PDFTEX\
+produces normal \DVI\ output, otherwise it generates \PDF\ output
+that looks identical to the \DVI\ output. An important aspect of this
+project is to investigate alternative justification algorithms (\eg\
+a~font expansion algorithm akin to the \HZ\ micro||typography algorithm by
+Prof.~Hermann Zapf), optionally making use of Multiple Master fonts.
+
+\PDFTEX\ is based on the original \TEX\ sources and \WEBC, and has been
+successfully compiled on \UNIX, \WIN\ and \MSDOS\ systems. It is under
+active development, with new features trickling in. Great care is taken
+to keep new \PDFTEX\ versions backward compatible with earlier ones.
+
+For some years there has been a~\quote {moderate} successor to \TEX\
+available, called \ETEX. Because mainstream macro packages such as
+\LATEX\ have started supporting this welcome extension, the \ETEX\
+functionality has also been integrated into the \PDFTEX\ code. For a
+while (\TEXLIVE~2004 and~2005) \PDFTEX\ therefore came in two flavours:
+the \ETEX\ enabled \PDFETEX\ engine and the standard one, \PDFTEX. The
+ability to produce both \PDF\ and \DVI\ output made \PDFETEX\ the primary
+\TEX\ engine in these distributions. Since \PDFTEX\ version 1.40 now the
+\ETEX\ extensions are part already of the \PDFTEX\ engine, so there is
+no need anymore to ship \PDFETEX. The \ETEX\ functionality of \PDFTEX\
+can be disabled if not required. Other extensions are \MLTEX\ and \ENCTEX;
+these are also included in the current \PDFTEX\ code.
+
+\PDFTEX\ is maintained by \THANH, Martin Schr\"oder, Hans Hagen, Taco
+Hoekwater, Hartmut Henkel, and others. The \PDFTEX\ homepage is \from
+[ptex_org]. Please send \PDFTEX\ comments and bug reports to the mailing
+list \from [ptex_bugs].
+
+We thank all readers who send us corrections and suggestions. We also
+wish to express the hope that \PDFTEX\ will be of as much use to you
+as it is to us.  Since \PDFTEX\ is still being improved and extended,
+we suggest you to keep track of updates.
+
+%***********************************************************************
+
+\subsection{About this manual}
+
+This manual revision (\rcsrevision) tries to keep track with the recent
+\PDFTEX\ development up to version \currentpdftex. Main text updates
+were done regarding the new configuration scheme, font mapping, and new
+or updated primitives.  The primary repository for the manual and its
+sources is at \from[ptex_sarovar].  Copies in \PDF\ format can also be
+found at the CTAN network in directory \from[ptex_ctan].
+
+Thanks to Karl Berry for proof reading and submitting a~long changes
+list. New errors might have slipped in afterwards by the editor.
+Please send questions or suggestions by email to \from[ptex_bugs].
+
+%***********************************************************************
+
+\subsection{Legal Notice}
+
+Copyright \copyright\ 1996||2007  \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;
+with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+A~copy of the license is included in the section entitled ``GNU
+Free Documentation License''.
+
+%***********************************************************************
+
+\section{About \PDF}
+
+The cover of this manual lists an almost minimal \PDF\ file generated
+by \PDFTEX, with the corresponding source file on the next page. Unless
+compression is enabled, such a~\PDF\ file is rather verbose and readable.
+The first line specifies the version used; currently \PDFTEX\ produces
+level 1.4 output by default. \PDF\ viewers are supposed to silently skip
+over all elements they cannot handle.
+
+A~\PDF\ file consists of objects. These objects can be recognized by their
+number and keywords:
+
+\starttyping
+9 0 obj << /Type /Catalog /Pages 5 0 R >> endobj
+\stoptyping
+
+Here \typ{9 0 obj ... endobj} is the object capsule. The first number
+is the object number. The sequence \type{5 0 R} is an object reference,
+a~pointer to another object (no.~5). The second number (here a~zero)
+is currently not used in \PDFTEX; it is the version number of the
+object. It is for instance used by \PDF\ editors, when they replace
+objects by new ones.
+
+When a~viewer opens a~\PDF\ file, it goes right 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 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
+\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
+points to an object (no.~10) with a~bit more about the document. Just
+follow the thread:
+
+\startnarrower
+\type{/Root}     $\longrightarrow$ object~9 $\longrightarrow$
+\type{/Pages}    $\longrightarrow$ object~5 $\longrightarrow$
+\type{/Kids}     $\longrightarrow$ object~2 $\longrightarrow$
+\type{/Contents} $\longrightarrow$ object~3
+\stopnarrower
+
+As soon as we add annotations, a~fancy word for hyperlinks and the like,
+some more entries will be present in the catalog. We invite users to
+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
+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
+operands. Between \type{BT} and \type{ET} comes the text. A~font is
+selected by a~\type{Tf} operator, which is given a~font resource name
+\type{/F..} and the font size. The actual text goes into \type{()}
+bracket pairs so that it creates a~\POSTSCRIPT\ string. The numbers
+inbetween bracket pairs provide horizontal movements like spaces and
+fine glyph positioning (kerning). When one analyzes a~file produced by
+a~less sophisticated typesetting engine, whole sequences of words can
+be recognized. In \PDF\ files generated by \PDFTEX\ however, many words
+come out rather fragmented, mainly because a~lot of kerning takes place;
+in our example the \type{80} moves the text \type{(elcome)} left towards
+the letter \type{(W)} by 80/1000 of the font size. \PDF\ viewers in search
+mode simply ignore the kerning information in these text streams. When
+a~document is searched, the search engine reconstructs the text from these
+(string) snippets.
+
+Every \type{/Page} object points also to a~\type{/Resources} object
+(no.~1) that gives all ingredients needed to assemble the page. In our
+example only a~\type{/Font} object (no.~4) is referenced, which in turn
+tells that the text is typeset in \type{/Font} \type{/Times-Roman}. The
+\type{/Font} object points also to a~\type{/Widths} array (object no.~7)
+that tells for each character by how much the viewer must move forward
+horizontally after typesetting a~glyph. More details about the font
+can be found in the \type{/FontDescriptor} object (no.~8); if a~font
+file is embedded, this object points to the font program stream. But as
+the Times-Roman font used for our example is one of the 14 so||called
+standard fonts that should always be present in any \PDF\ viewer and
+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.
+
+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.
+
+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 the number. So
+
+\starttyping
+\pdfobj{/Type /Catalog /Pages 5 0 R}
+\stoptyping
+
+inserts an object into the \PDF\ file, while \type{\pdflastobj}
+returns the number \PDFTEX\ assigned to this object. Unless objects
+are referenced by others, they will just end up as isolated entities,
+not doing any real harm but bloating the \PDF\ file. In general this
+rather direct way of pushing objects in the \PDF\ files 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,
+\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.
+
+%***********************************************************************
+
+\section{Getting started}
+
+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 \CMACTEX. The ready to run \TEXLIVE\
+distribution comes with \PDFTEX\ versions for many \UNIX, \WIN, and
+\MACOSX\ systems; more information can be found at \from[texlive]. \TETEX\
+by Thomas Esser is a~source distribution with an automated compilation
+process for \UNIX\ systems; see \from[tetex]. For \WIN\ systems there
+are also three separate distributions that contain \PDFTEX, all in
+\from[win32]: \XEMTEX\ by Fabrice Popineau, \MIKTEX\ by Christian Schenk,
+and \PROTEXT\ (based on \MIKTEX) by Thomas Feuerstack. So when you use
+any of these distributions, you don't need to bother with the \PDFTEX\
+installation procedure in the next sections.
+
+If there is no precompiled \PDFTEX\ binary for your system, or the version
+coming with a~distribution is not the current one and you would like to
+try out a~fresh \PDFTEX\ immediately, you will need to build \PDFTEX\
+from sources; read on. You should already have a~working \TEX\ system,
+\eg\ \TEXLIVE\ or \TETEX, into which the freshly compiled \PDFTEX\ will
+be integrated. Note that the installation description in this manual
+is \WEBC||specific.
+
+%***********************************************************************
+
+\subsection{Getting sources and binaries}
+
+The latest sources of \PDFTEX\ are currently distributed for compilation
+on \UNIX\ systems (including Linux), and \WIN\ systems (Windows 95,
+98, NT, 2000, XP).  The primary location where one can fetch the latest
+released code is at the developers' homepage \from[ptex_sarovar], where
+you also find bug tracking information, and the manual sources. Download
+the \PDFTEX\ archive from there.
+
+The \PDFTEX\ sources can also be found at their canonical place in
+the CTAN network, \from[ptex_ctan].
+Separate \PDFTEX\ binaries for various systems might also be available,
+check out the subdirectories below \from[ctan_systems].
+
+%***********************************************************************
+
+\subsection{Compiling}
+
+The compilation is expected to be easy on \UNIX||like systems and
+can be described best by example. Assuming that the file \filename
+{pdftex.zip} is downloaded to some working directory, \eg\
+\filename {\$HOME/pdftex}, on a~\UNIX\ system the following steps are
+needed to compile \PDFTEX:
+
+\startesctyping
+cd $HOME/pdftex
+unzip pdftex-@currentpdftex.zip
+cd pdftex-@currentpdftex
+./build.sh
+\stopesctyping
+
+The binary \filename{pdftex} is then built in the subdirectory
+\filename{build/texk/web2c}. In the same directory also the corresponding
+pool file \filename{pdftex.pool} is generated; it's needed for creating
+the format files.
+
+The obsolescent binary \filename{pdfetex} is still generated for backward
+compatibility, but since version 1.40 it is just a~file copy
+of the file \filename{pdftex}.
+
+Together with the \filename{pdftex} binary also the \filename{pdftosrc}
+and \filename{ttf2afm} binaries are generated.
+
+%***********************************************************************
+
+\subsection{Placing files}
+
+The next step is to put the freshly compiled \filename{pdftex},
+\filename{pdftosrc}, and \filename{ttf2afm} binaries and the
+pool file \filename{pdftex.pool} into their proper places within
+the \TDS\ structure of the \TEX\ system. Put the binary files
+into the binary directory (\eg\ for a~typical \TEXLIVE\ system)
+\filename{/usr/local/texlive/2006/bin/x86_64-linux}, and the pool file
+into \filename{/usr/local/texlive/2006/texmf/web2c}.
+
+Don't forget to do a~\filename{texconfig-sys init} afterwards, so that
+all formats are regenerated system-wide with the fresh \filename{pdftex}
+binary.
+
+%***********************************************************************
+
+\subsection{Setting search paths}
+
+\WEBC||based programs, including \PDFTEX, use the \WEBC\ run||time
+configuration file called \filename {texmf.cnf}.  The location
+of this file is the appropriate position within the \TDS\ tree
+relative to the place of the \PDFTEX\ binary; on a~\TEXLIVE\ system,
+file \filename{texmf.cnf} typically is located either in directory
+\filename{texmf/web2c} or \filename{texmf-local/web2c}.  The path to
+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.
+
+\PDFTEX\ uses the search path variables shown in \in{table}[tbl:spathvar].
+
+\startbuffer
+\starttabulate[|l|l|]
+\HL
+\NC \bf used for        \NC \bf texmf.cnf        \NC\NR
+\HL
+\NC output files        \NC \type{TEXMFOUTPUT}   \NC\NR
+\NC input files, images \NC \type{TEXINPUTS}     \NC\NR
+\NC format files        \NC \type{TEXFORMATS}    \NC\NR
+\NC text pool files     \NC \type{TEXPOOL}       \NC\NR
+\NC encoding files      \NC \type{ENCFONTS}      \NC\NR
+\NC font map files      \NC \type{TEXFONTMAPS}   \NC\NR
+\NC \TFM\ files         \NC \type{TFMFONTS}      \NC\NR
+\NC virtual fonts       \NC \type{VFFONTS}       \NC\NR
+\NC type1 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
+\HL
+\stoptabulate
+\stopbuffer
+
+\placetable[here][tbl:spathvar]
+  {The \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.)
+
+\PathDescription {TEXINPUTS} This variable specifies where \PDFTEX\ finds
+its input files. Image files are considered
+input files and searched for along this path.
+
+\PathDescription {TEXFORMATS} Search path for format (\type{.fmt}) files.
+
+\PathDescription {TEXPOOL} Search path for pool (\type{.pool}) files.
+
+\PathDescription {ENCFONTS} Search path for encoding (\type{.enc}) files.
+
+\PathDescription {TEXFONTMAPS} Search path for font map (\type{.map}) files.
+
+\PathDescription {TFMFONTS} Search path for font metric (\type{.tfm}) files.
+
+\PathDescription {VFFONTS} Search path for virtual font (\type{.vf})
+files.  Virtual fonts are fonts made up of other fonts.
+Because \PDFTEX\ produces the
+final output code, it must consult those files.
+
+\PathDescription {T1FONTS} Search path for Type~1 font files (\type{.pfa}
+and \type{.pfb}).  These outline (vector) fonts are to be preferred over
+bitmap \PK\ fonts. In most cases Type~1 fonts are used and this variable
+tells \PDFTEX\ where to find them.
+
+\PathDescription {TTFFONTS, OPENTYPEFONTS} Search paths for TrueType
+(\type{.ttf}) and OpenType (\type{.otf}) font files.  Like Type~1 fonts,
+TrueType and OpenType fonts are also outlines.
+
+\PathDescription {PKFONTS} Search path for packed (bitmap) font
+(\type{.pk}) files.
+Unfortunately bitmap fonts are still displayed poorly by some \PDF\
+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).
+
+%***********************************************************************
+
+\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).
+
+When \TEX\ builds a~page, it places items relative to the top left page
+corner (the \DVI\ reference point). Separate \DVI\ postprocessors allow
+specifying the paper size (\eg\ \quote {A4} or \quote{letter}), so
+that this reference point is moved to the correct position on the paper,
+and the text ends up at the right place.
+
+In \PDF, the paper dimensions are part of the page definition, and
+\PDFTEX\ therefore requires that they be defined at the beginning of
+the \PDFTEX\ run. As with pages described by \POSTSCRIPT, the \PDF\
+reference point is in the lower||left corner.
+
+Formerly, these dimensions and other \PDFTEX\ parameters were read
+in from a~configuration file named \filename{pdftex.cfg}, which had
+a~special (non-\TEX) format, at the start of processing.  Nowadays such
+a~file is ignored by \PDFTEX.  Instead, the page dimensions and offsets,
+as well as many other parameters, can be set by \PDFTEX\ primitives
+during the \PDFTEX\ format building process, so that the settings are
+dumped into the fresh format and consequently will be used when \PDFTEX\
+is later called with that format. All settings from the format can
+still be overridden during a~\PDFTEX\ run by using the same primitives.
+This new configuration concept is a~more unified approach, as it avoids
+the configuration file with a~special format.
+
+A~list of \PDFTEX\ primitives relevant for setting up the \PDFTEX\ engine
+is given in \in{table}[tbl:configparms]. All primitives are described in
+detail within later sections. \in{Figure}[in:pdftexconfig] shows a~recent
+configuration file (\type{pdftexconfig.tex}) in \TEX\ format, using the
+primitives from \in{table}[tbl:configparms], which typically is read
+in during the format building process. It enables \PDF\ output, sets paper
+dimensions and the default pixel density for \PK\ font inclusion. The default
+values are chosen so that \PDFTEX\ often can be used (\eg\ in \type{-ini} mode)
+even without setting any parameters.
+
+\startbuffer
+\starttabulate[|l|l|l|l|l|]
+\HL
+\NC \bf internal name              \NC \bf type  \NC\bf default\NC\bf comment\NC\NR
+\HL
+\NC \type{\pdfoutput}              \NC integer   \NC      0 \NC \DVI                 \NC\NR
+\NC \type{\pdfadjustspacing}       \NC integer   \NC      0 \NC off                  \NC\NR
+\NC \type{\pdfcompresslevel}       \NC integer   \NC      9 \NC best                 \NC\NR
+\NC \type{\pdfobjcompresslevel}    \NC integer   \NC      0 \NC no object streams    \NC\NR
+\NC \type{\pdfdecimaldigits}       \NC integer   \NC      4 \NC max.                 \NC\NR
+\NC \type{\pdfimageresolution}     \NC integer   \NC     72 \NC dpi                  \NC\NR
+\NC \type{\pdfpkresolution}        \NC integer   \NC      0 \NC 72\,dpi              \NC\NR
+\NC \type{\pdfpkmode}              \NC token reg.\NC  empty \NC mode set in \type{mktex.cnf} \NC\NR
+\NC \type{\pdfuniqueresname}       \NC integer   \NC      0 \NC                      \NC\NR
+\NC \type{\pdfprotrudechars}       \NC integer   \NC      0 \NC                      \NC\NR
+\NC \type{\pdfminorversion}        \NC integer   \NC      4 \NC \PDF\ 1.4            \NC\NR
+\NC \type{\pdfforcepagebox}        \NC integer   \NC      0 \NC                      \NC\NR
+\NC \type{\pdfinclusionerrorlevel} \NC integer   \NC      0 \NC                      \NC\NR
+%-----------------------------------------------------------------------
+\NC \type{\pdfhorigin}             \NC dimension \NC  1\,in \NC                      \NC\NR
+\NC \type{\pdfvorigin}             \NC dimension \NC  1\,in \NC                      \NC\NR
+\NC \type{\pdfpagewidth}           \NC dimension \NC  0\,pt \NC                      \NC\NR
+\NC \type{\pdfpageheight}          \NC dimension \NC  0\,pt \NC                      \NC\NR
+\NC \type{\pdflinkmargin}          \NC dimension \NC  0\,pt \NC                      \NC\NR
+\NC \type{\pdfdestmargin}          \NC dimension \NC  0\,pt \NC                      \NC\NR
+\NC \type{\pdfthreadmargin}        \NC dimension \NC  0\,pt \NC                      \NC\NR
+\NC \type{\pdfmapfile}             \NC text      \NC \filename{pdftex.map} \NC not dumped\NC\NR
+\HL
+\stoptabulate
+\stopbuffer
+
+\placetable[here][tbl:configparms]
+  {The set of \PDFTEX\ configuration parameters.}
+  {\getbuffer}
+
+\startbuffer
+\tx\setupinterlinespace
+\startframedtext
+\starttyping
+% Set pdfTeX parameters for pdf mode (replacing pdftex.cfg file).
+% Thomas Esser, 2004. public domain.
+\pdfoutput=1
+\pdfpagewidth=210 true mm
+\pdfpageheight=297 true mm
+\pdfpkresolution=600
+\endinput
+\stoptyping
+\stopframedtext
+\stopbuffer
+
+\placefigure[here][in:pdftexconfig]
+  {A typical configuration file (\filename{pdftexconfig.tex}).}
+  {\getbuffer}
+
+Independent of whether such a~configuration file is read or not, the
+first action in a~\PDFTEX\ run is that the program reads the global \WEBC\
+configuration file (\filename{texmf.cnf}), which is common to all programs
+in the \WEB2C\ system. This file mainly defines file search paths, the
+memory layout (\eg\ pool and hash size), and other general parameters.
+
+%***********************************************************************
+
+\subsection{Creating format files}
+
+\startbuffer
+\tx\setupinterlinespace
+\startframedtext
+\starttyping
+% Thomas Esser, 1998, 2004. public domain.
+\ifx\pdfoutput\undefined
+\else
+  \ifx\pdfoutput\relax
+  \else
+    \input pdftexconfig
+    \pdfoutput=0
+  \fi
+\fi
+\input etex.src
+\dump
+\endinput
+\stoptyping
+\stopframedtext
+\stopbuffer
+
+\placefigure[here][in:etexini]
+  {File \type{etex.ini} for \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
+\scrollmode
+\input latex.ltx
+\endinput
+\stoptyping
+\stopframedtext
+\stopbuffer
+
+\placefigure[here][in:pdflatexini]
+  {File \type{pdflatex.ini} for \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.
+
+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:
+
+\starttyping
+pdftex -ini *etex.ini
+pdftex -ini pdflatex.ini
+\stoptyping
+
+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.
+
+\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
+
+\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
+\stoptyping
+
+for an English format, or
+
+\starttyping
+texexec --make en de
+\stoptyping
+
+for an English and German one. Most users will simply say:
+
+\starttyping
+texexec --make --all [--alone]
+\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}
+
+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:
+
+\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.
+
+%***********************************************************************
+
+\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
+can be found in the \WEBC\ documentation.
+
+Variables in \filename {texmf.cnf} can be overwritten by environment
+variables. Here are some of the most common problems you can encounter when
+getting started:
+
+\startitemize
+
+\head  \type{I can't read pdftex.pool; bad path?}
+
+       \type{TEXMFCNF} is not set correctly and so \PDFTEX\ cannot find
+       \type{texmf.cnf}, or \type{TEXPOOL} in \filename {texmf.cnf}
+       doesn't contain a~path to the pool file \filename {pdftex.pool}.
+
+\head  \type{You have to increase POOLSIZE.}
+
+       \PDFTEX\ cannot find \filename {texmf.cnf}, or the value of \type
+       {pool_size} specified in \filename {texmf.cnf} is not large enough
+       and must be increased. If \type{pool_size} is not specified in
+       \filename {texmf.cnf} then you can add something like
+
+\starttyping
+pool_size=500000
+\stoptyping
+
+\head  \type{I can't find the format file `pdftex.fmt'!} \crlf
+       \type{I can't find the format file `pdflatex.fmt'!}
+
+       The format file is not created (see above how to do that) or
+       is not properly placed. Make sure that \type{TEXFORMATS} in
+       \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}
+
+       This appears \eg\ if you forgot to regenerate the \type{.fmt}
+       files after installing a~new version of the \PDFTEX\ binary and
+       \filename {pdftex.pool}. The first line tells by which engine
+       the offending format was generated.
+
+\head  \type{TEX.POOL doesn't match; TANGLE me again!} \crlf
+       \type{TEX.POOL doesn't match; TANGLE me again (or fix the path).}
+
+       This might appear if you forgot to install the proper \filename
+       {pdftex.pool} when installing a~new version of the \PDFTEX\
+       binary. \Eg\ under \TEXLIVE\ then run \type{texconfig-sys init}
+       as root.
+
+%\head  \type{! I can't find file `*pdftex.ini'.} \crlf
+%       \type{<*> *pdftex.ini}
+%
+%       This typically appears when you try to generate an extended format
+%       with the \PDFTEX\ engine (it does not know about the special asterisk
+%       \type{*} notation). Use the \PDFETEX\ engine instead.
+
+\head  \PDFTEX\ cannot find one or more map files (\type{*.map}),
+       encoding vectors (\type{*.enc}), virtual fonts, Type~1 fonts,
+       TrueType or OpenType fonts, or some image file.
+
+       Make sure that the required file exists and the corresponding variable
+       in \filename {texmf.cnf} contains a~path to the file. See above which
+       variables \PDFTEX\ needs apart from the ones \TEX\ uses.
+
+       When you have installed new fonts, and your \PDF\ viewer complains
+       about missing fonts, you should take a~look at the log file produced
+       by \PDFTEX. Missing fonts, map files, encoding vectors as well as
+       missing characters (glyphs) are reported there.
+
+\stopitemize
+
+Normally the page content takes one object. This means that one seldomly
+finds more than a~few hundred objects in a~simple file. This \PDFTEX\
+manual for instance uses approx.~750 objects. In more complex applications
+this number can grow quite rapidly, especially when one uses a~lot of
+widget annotations, shared annotations or other shared things. In any
+case \PDFTEX's internal object table size will automatically grow to the
+required size (the parameter \type{obj_tab_size} for manual control of
+the object table size is now obsolete and ignored).
+
+%***********************************************************************
+
+\section{Macro packages supporting \PDFTEX}
+
+As \PDFTEX\ generates the final \PDF\ output without help of
+a~postprocessor, macro packages that take care of these \PDF\ features
+have to be set up properly.  Typical tasks are handling color,
+graphics, hyperlink support, threading, font||inclusion, as well as
+page imposition and manipulation.  All these \PDF||specific tasks can be
+commanded by \PDFTEX's own primitives (a few also by a~\PDFTEX||specific
+\type{\special{pdf: ...}} primitive). Any other \type{\special{}} commands,
+like the ones defined for various \DVI\ postprocessors, are simply
+ignored by \PDFTEX\ when in \PDF\ output mode; a~warning is given only
+for non||empty \type{\special{}} commands.
+
+When a~macro package already written for classical \TEX\ with \DVI\ output
+is to be modified for use with \PDFTEX, it is very helpful to get some
+insight to what extent \PDFTEX||specific support is needed. This info can
+be gathered \eg\ by outputting the various \type{\special} commands
+as \type{\message}. Simply type
+
+\starttyping
+\pdfoutput=1 \let\special\message
+\stoptyping
+
+or, if this leads to confusion,
+
+\starttyping
+\pdfoutput=1 \def\special#1{\write16{special: #1}}
+\stoptyping
+
+and see what happens. As soon as one \quote {special} message turns up, one
+knows for sure that some kind of \PDFTEX\ specific support is needed, and
+often the message itself gives a~indication of what is needed.
+
+Currently all mainstream macro packages offer \PDFTEX\ support, with
+automatic detection of \PDFTEX\ as engine. So there is normally no need
+to turn on \PDFTEX\ support explicitly.
+
+\startitemize
+
+\item  For \LATEX\ users, Sebastian Rahtz' and Heiko Oberdiek's \type
+       {hyperref} package has substantial support for \PDFTEX\ and
+       provides access to most of its features.  In the simplest and
+       most common case, the user merely needs to load \type{hyperref},
+       and all cross||references will be converted to \PDF\ hypertext
+       links. \PDF\ output is automatically selected, compression is
+       turned on, and the page size is set up correctly. Bookmarks are
+       created to match the table of contents.
+
+\item  The standard \LATEX\ \type{graphics}, \type{graphicx}, and
+       \type{color} packages also have automatic \pdfTeX\ support, which
+       allow use of color, text rotation, and graphics inclusion commands.
+
+\item  The \CONTEXT\ macro package by Hans Hagen has very full support
+       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.
+
+\item  \PDF\ from \TEXINFO\ documents can be created by running \PDFTEX\ on
+       the \TEXINFO\ file, instead of \TEX.  Alternatively, run the shell
+       command \type{texi2pdf} instead of \type{texi2dvi}.
+
+\item A~small modification of \filename {webmac.tex}, called \filename
+       {pdfwebmac.tex}, allows production of hyperlinked \PDF\ versions
+       of the program code written in \WEB.
+
+\stopitemize
+
+Some nice samples of \PDFTEX\ output can be found at
+\from[ptex_org], \from[context], and \from[tex_showcase].
+
+%***********************************************************************
+
+\section{Setting up fonts}
+
+\PDFTEX\ can work with Type~1 and TrueType fonts (and to some extent also
+with OpenType fonts). Font files should be available and embedded for all
+fonts used in the document. It is possible to use \METAFONT||generated
+fonts in \PDFTEX\ --- but it is strongly recommended not to use these
+fonts if an equivalent is available in Type~1 or TrueType format, if
+only because bitmap Type~3 fonts render very poorly in (older versions
+of) Adobe Reader. Given the free availability of Type~1 versions of all
+the Computer Modern fonts, and the ability to use standard \POSTSCRIPT\
+fonts, there is rarely a~need to use bitmap fonts in \PDFTEX.
+
+%***********************************************************************
+
+\subsection[mapfile]{Map files}
+
+Font map files provide the connection between \TEX\ \TFM\ font files
+and the outline font file names. They contain also information about
+re||encoding arrays, partial font embedding (``subsetting''), and
+character transformation parameters (like SlantFont and ExtendFont). Those
+map files were first created for \DVI\ postprocessors. But, as \PDFTEX\
+in \PDF\ output mode includes all \PDF\ processing steps, it also needs
+to know about font mapping, and therefore reads in one or more map files.
+Map files are not read in when \PDFTEX\ is in \DVI\ mode. Pixel fonts
+can be used without being listed in the map file.
+
+By default, \PDFTEX\ reads the map file \filename{pdftex.map}.  In \WEBC,
+map files are searched for using the \type{TEXFONTMAPS} config file value
+and environment variable.  By default, the current directory and various
+system directories are searched.
+
+Within the map file, each font is listed on an individual line.  The syntax of
+each line is upward||compatible with \type{dvips} map files and can contain
+the following fields (some are optional; explanations follow):
+
+\startnarrower
+{\em tfmname basename fontflags special encodingfile fontfile}
+\stopnarrower
+
+It is mandatory that {\em tfmname} is the first field. If
+a~{\em basename} is given, it must be the second field. Similarly if
+{\em fontflags} is given it must be the third field (if {\em basename}
+is present) or the second field (if {\em basename} is left out). It is
+possible to mix the positions of {\em special}, {\em encodingfile},
+and {\em fontfile}, however the first three fields must be given in
+fixed order.
+
+\startdescription {tfmname}
+
+sets the name of the \TFM\ file for a~font --- the name \TEX\ sees.
+This name must always
+be given.
+
+\stopdescription
+
+\startdescription {basename}
+
+sets the (\POSTSCRIPT) base font name, which has two uses:
+
+First, when a~\PDF\ file is embedded by \type{\pdfximage}, the
+\type{/BaseFont} names in the font dictionaries of Type~1 and Type~1C
+(CFF) fonts from the embedded \PDF\ file are checked against this {\em
+basename} field. If names match, the glyphs of that font will not be
+copied from the embedded \PDF\ file, but instead a~local font is opened,
+and all needed glyphs will be taken from the Type~1 font file that is
+mentioned in the map line (see {\em fontfile} below). By this collecting
+mechanism Type~1 glyphs can be shared between several embedded \PDF\
+files and with text that is typeset by \pdfTeX, which helps keeping the
+resulting \PDF\ file size small, if many files with similar Type~1(C)
+fonts are embedded. Replacing Type1 fonts from embedded \PDF\ files
+requires that also a~Type1 font file name is in the {\em fontfile} field
+(see below).
+
+Second, if a~font file is not to be embedded into the \PDF\ output
+({\em fontfile} field missing), then the {\em basename} field will be
+copied to the \type{/BaseFont} and \type{/FontName} dictionary entries
+in the \PDF\ file, so that the \POSTSCRIPT\ font name will be known to
+the consumer application (\eg\ viewer).
+
+It is highly recommended to always use the {\em basename} field (but
+strictly speaking it's optional).
+
+\stopdescription
+
+\startdescription {fontflags}
+
+specify some characteristics of the font. The following description of
+these flags is taken, with slight modification, from the \PDFReference\
+(the section on font descriptor flags). Viewers can adapt their rendering
+to these flags, especially when they substitute a~non-embedded font by
+some own approximation.
+
+\startnarrower
+
+The value of the flags key in a~font descriptor is a~32||bit integer that
+contains a~collection of boolean attributes. These attributes are true if the
+corresponding bit is set to~1. \in{Table}[flags] specifies the meanings of
+the bits, with bit~1 being the least significant. Reserved bits must be set
+to zero.
+
+\startbuffer
+\starttabulate[|c|l|]
+\HL
+\NC \bf bit position \NC \bf semantics                               \NC\NR
+\HL
+\NC 1                \NC Fixed||width font                           \NC\NR
+\NC 2                \NC Serif font                                  \NC\NR
+\NC 3                \NC Symbolic font                               \NC\NR
+\NC 4                \NC Script font                                 \NC\NR
+\NC 5                \NC Reserved                                    \NC\NR
+\NC 6                \NC Uses the Adobe Standard Roman Character Set \NC\NR
+\NC 7                \NC Italic                                      \NC\NR
+\NC 8--16            \NC Reserved                                    \NC\NR
+\NC 17               \NC All||cap font                               \NC\NR
+\NC 18               \NC Small||cap font                             \NC\NR
+\NC 19               \NC Force bold at small text sizes              \NC\NR
+\NC 20--32           \NC Reserved                                    \NC\NR
+\HL
+\stoptabulate
+\stopbuffer
+
+\placetable
+  [here][flags]
+  {The meaning of flags in the font descriptor.}
+  {\getbuffer}
+
+All characters in a~{\em fixed||width} font have the same width, while
+characters in a~proportional font have different widths. Characters in a~{\em
+serif font} have short strokes drawn at an angle on the top and bottom of
+character stems, while sans serif fonts do not have such strokes. A~{\em
+symbolic font} contains symbols rather than letters and numbers. Characters
+in a~{\em script font} resemble cursive handwriting. An {\em all||cap} font,
+which is typically used for display purposes such as titles or headlines,
+contains no lowercase letters. It differs from a~{\em small||cap} font in
+that characters in the latter, while also capital letters, have been sized
+and their proportions adjusted so that they have the same size and stroke
+weight as lowercase characters in the same typeface family.
+
+Bit~6 in the flags field indicates that the font's character set
+conforms to the
+Adobe Standard Roman Character Set, or a~subset of that, and that it uses
+the standard names for those characters.
+
+Finally, bit~19 is used to determine whether or not bold characters are
+drawn with extra pixels even at very small text sizes. Typically, when
+characters are drawn at small sizes on very low resolution devices such
+as display screens, features of bold characters may appear only one pixel
+wide. Because this is the minimum feature width on a~pixel||based device,
+ordinary non||bold characters also appear with one||pixel wide features,
+and thus cannot be distinguished from bold characters. If bit~19 is set,
+features of bold characters may be thickened at small text sizes.
+
+\stopnarrower
+
+If the {\em fontflags} field is not given, \PDFTEX\ treats it as being~4,
+a~symbolic font. If you do not know the correct value, it is best not
+to specify it at all, as specifying a~bad value of font flags may cause
+troubles in viewers. On the other hand this option is not absolutely
+useless because it provides backward compatibility with older map files
+(see the {\em fontfile} description below).
+
+\stopdescription
+
+\startdescription {special}
+
+instructions can be used to manipulate fonts similar to the way
+\type{dvips} does. Currently only the keywords \type{SlantFont}
+and \type{ExtendFont} are interpreted, other instructions (as
+\type{ReEncodeFont} with parameters, see {\em encoding} below) are
+just ignored.  The permitted \type{SlantFont} range is $-$1..1;
+for \type{ExtendFont} it's $-$2..2.  The block of {\em special}
+instruction must be enclosed by double quotes \type{"}.
+
+\stopdescription
+
+\startdescription {encodingfile}
+
+specifies the name of the file containing the external encoding vector
+to be used for the font. The encoding file must have name extension
+\type{.enc}, and the full file name including this extension must be given
+with preceding~\type{<} character. The format of the encoding vector is
+identical to that used by \type{dvips}. If no encoding is specified,
+the font's built||in default encoding is used. The {\em encodingfile}
+field may be omitted if you are sure that the font resource has the
+correct built||in encoding. In general this option is highly recommended,
+and it is {\em required} when subsetting a~TrueType font.
+
+\stopdescription
+
+\startdescription {fontfile}
+
+sets the name of the font file to be embedded into the \PDF\ output for a
+given \TeX\ font (the {\em tfmname}~$\longleftrightarrow$~{\em fontfile}
+mapping is the most prominent use of the \filename{pdftex.map} file).
+The font file name must belong to a~Type~1 or TrueType font file. If
+the {\em fontfile} field is missing, no font embedding can take place;
+in case the {\em basename} field does not contain one of the 14 standard
+font names also a~warning will be given. Not embedding a~font into a~\PDF\
+file might be troublesome, as it requires that the font or some similar
+looking replacement font is available within the \PDF\ viewer, so that
+it can render the glyphs with its own font version.
+
+The font file name should be preceded by one or two special characters,
+which tells how to handle the font file:
+
+\startitemize
+
+\item  If the font file name is preceded by a~\type{<} character, the
+       font file will be only partially embedded  into the \PDF\ file
+       (``subsetted''), meaning that only used glyphs are going into
+       the \PDF\ file. This is the most common use and is {\em strongly
+       recommended} for any font, as it ensures the portability and
+       reduces the size of the \PDF\ output. Subsetted fonts are included
+       in such a~way that name and cache clashes are minimized.
+
+\item  If the font file name is preceded by a~double \type{<<}, the font
+       file will be included entirely --- all glyphs of the font
+       are embedded, including even the ones that are not used in the
+       document. Apart from causing large size \PDF\ output, this option
+       may cause troubles with TrueType fonts, so it is normally not
+       recommended for Type1 or TrueType fonts. But this is currently
+       the only mode that allows the use of OpenType fonts. This mode
+       might also be useful in case the font is atypical and can not be
+       subsetted well by \PDFTEX. {\em Beware: some font vendors forbid
+       full font inclusion.}
+
+\item  The case that no special character precedes the font file name
+       is deprecated since \PDFTEX\ version 1.40.0. These font files are
+       now completely ignored, and a~corresponding warning is given. You
+       achieve exactly the same \PDF\ result if you just remove the
+       font file name from the map entry. Then the glyph widths that go
+       into the \PDF~file are extracted from the \TFM~file, and a~font
+       descriptor object is created that contains approximations of the
+       font metrics for the selected font.
+
+       This option is useful only as fallback when you do not want to
+       embed the font (\eg\ due to font license restrictions), but wish to
+       use the font metrics and let the \PDF\ viewer generate instances
+       that look close to the used font in case the font resource is not
+       installed on the system where the \PDF\ output will be viewed
+       or printed. To use this feature, the font flags {\em must} be
+       specified, and it must have the bit~6 set on, which means that
+       only fonts with the Adobe Standard Roman Character Set can be
+       simulated. The only exception is the case of a~Symbolic font,
+       which is not very useful.
+
+\stopitemize
+
+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.
+
+\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
+a~\PDF\ Type~3 font, created by \METAPOST\ using some utilities by Hans
+Hagen. In general \PGC\ files can contain whatever is allowed in a~\PDF\ page
+description, which may be used to support fonts that are not available
+in \METAFONT. \PGC\ fonts are not widely useful, as vector Type~3 fonts
+are not displayed very well in older versions of Acrobat Reader, but may
+be more useful when better Type~3 font handling is more common.}. If no
+\PGC\ source is available, \PDFTEX\ will try to use \PK~fonts as \DVI\
+drivers do, creating \PK~fonts on||the||fly if needed.
+
+Lines containing nothing apart from {\em tfmname} stand for scalable
+Type~3 fonts. For scalable fonts as Type~1, TrueType and scalable Type~3
+font, all the fonts loaded from a~\TFM\ at various sizes will be included
+only once in the \PDF\ output. Thus if a~font, let's say \type{csr10}, is
+described in one of the map files, then it will be treated as scalable. As
+a~result the font source for csr10 will be included only once for
+\type{csr10}, \type{csr10 at 12pt} etc. So \PDFTEX\ tries to do its best
+to avoid multiple embedding of identical font sources. Thus vector \PGC\
+fonts should be specified as scalable Type~3 in map files like:
+
+\starttyping
+csr10
+\stoptyping
+
+It doesn't hurt much if a~scalable Type~3 font is not given in map files,
+except that the font source will be embedded into the \PDF\ file multiple
+times for various sizes, which causes a~much larger \PDF\ output. On
+the other hand if a~font in the map files is defined as scalable Type~3
+font and its \PGC\ source is not scalable or not available, \PDFTEX\
+will use \PK\ fonts instead; the \PDF\ output is still valid but some
+fonts may look ugly because of the scaled bitmap.
+
+To summarize this rather confusing story, we include some example lines.
+The most common way is to embed only a~glyph subset from a~font like this,
+with re||encoding:
+
+\starttyping
+ptmri8r Times-Italic <8r.enc <ptmri8a.pfb
+\stoptyping
+
+Without re||encoding it looks like this:
+
+\starttyping
+cmr10 CMR10 <cmr10.pfb
+\stoptyping
+
+A~SlantFont is specified similarly as for \type{dvips}. The \type
+{SlantFont} or \type{ExtendFont} entries work only with embedded Type1
+fonts:
+
+\starttyping
+psyro   StandardSymL ".167 SlantFont"         <usyr.pfb
+pcrr8rn Courier      ".85 ExtendFont" <8r.enc <pcrr8a.pfb
+\stoptyping
+
+Entirely embed a~font into the \PDF\ file without and with re||encoding:
+
+\starttyping
+fmvr8x MarVoSym         <<marvosym.pfb
+pgsr8r GillSans <8r.enc <<pgsr8a.pfb
+\stoptyping
+
+A~TrueType font can be used in the same way as a~Type~1 font:
+
+\starttyping
+verdana8r Verdana <8r.enc <verdana.ttf
+\stoptyping
+
+Now follow a few cases with non-embedded fonts. If the fontfile is
+missing, the viewer application will have to use its own approximation
+of the missing font (with and without re||encoding):
+
+\starttyping
+ptmr8r Times-Roman <8r.enc
+psyr Symbol
+\stoptyping
+
+In the next example the numerical font flags give some rough hint what
+general characteristics the GillSans font has, so \eg\ the Adobe Reader
+might try an approximation, if it doesn't have the font resource nor
+any clue how a font named GillSans should look like:
+
+\starttyping
+pgsr8r GillSans 32 <8r.enc
+\stoptyping
+
+Not embedding fonts is rather risky and should generally be avoided.
+If in doubt, always embed all fonts, even the 14 standard ones.
+
+%***********************************************************************
+
+\subsection{Helper tools for TrueType fonts}
+
+As mentioned above, \PDFTEX\ can work with TrueType fonts. Defining
+TrueType fonts is similar to Type~1. The only extra thing to do
+with TrueType is to create a~\TFM\ file. There is a~program called
+\type{ttf2afm} in the \PDFTEX\ distribution which can be used to
+extract \AFM\ from TrueType fonts (another conversion program is
+\type{ttf2pt1}). Usage of \type{ttf2afm} is simple:
+
+\starttyping
+ttf2afm -e <encoding vector> -o <afm outputfile> <ttf input file>
+\stoptyping
+
+ A~TrueType file can be recognized by its suffix \filename {ttf}. The optional
+{\em encoding} specifies the encoding, which is the same as the encoding
+vector used in map files for \PDFTEX\ and \type{dvips}. If the encoding is
+not given, all the glyphs of the \AFM\ output will be mapped to \type
+{/.notdef}. \type{ttf2afm} writes the output \AFM\ to standard output. If we
+need to know which glyphs are available in the font, we can run \type
+{ttf2afm} without encoding to get all glyph names. The resulting \AFM\ file
+can be used to generate a~\TFM\ one by applying \filename {afm2tfm}.
+
+To use a~new TrueType font the minimal steps may look like below. We suppose
+that \filename {test.map} is used.
+
+\starttyping
+ttf2afm -e 8r.enc -o times.afm times.ttf
+afm2tfm times.afm -T 8r.enc
+echo "times TimesNewRomanPSMT <8r.enc <times.ttf" >>test.map
+\stoptyping
+
+There are a~few limitations with TrueType fonts in comparison with
+Type~1 fonts:
+
+\startitemize[a,packed]
+\item  The special effects SlantFont|/|ExtendFont cannot be used.
+\item  To subset a~TrueType font, the font must be specified as re||encoded,
+       therefore an encoding vector must be given.
+\item  TrueType fonts coming with embedded \PDF\ files are kept
+       untouched; they are not replaced by local ones.
+\stopitemize
+
+%***********************************************************************
+
+\section{Formal syntax specification}
+
+This section formally specifies the \PDFTEX\ specific extensions to
+the \TEX\ macro programming language. All primitives are prefixed by
+\type {pdf} except for \type{\efcode}, \type{\lpcode}, \type{\rpcode},
+\type{\leftmarginkern}, and \type{\rightmarginkern}. The general
+definitions and syntax rules follow after the list of primitives.
+
+%%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,v 1.675 2007/01/25 10:37:13 hhenkel Exp $
+%%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 {\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 {\pdfdraftmode} \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 {\pdflinkmargin} \Whatever{dimen}
+}
+
+\Syntax {
+\Tex {\pdfdestmargin} \Whatever{dimen}
+}
+
+\Syntax {
+\Tex {\pdfthreadmargin} \Whatever{dimen}
+}
+
+\Syntax {
+\Tex {\pdfpxdimen} \Whatever{dimen}
+}
+
+% todo:
+\iffalse
+\Syntax {
+\Tex {\pdffirstlineheight} \Whatever{dimen}
+}
+
+\Syntax {
+\Tex {\pdflastlinedepth} \Whatever{dimen}
+}
+
+\Syntax {
+\Tex {\pdfeachlineheight} \Whatever{dimen}
+}
+
+\Syntax {
+\Tex {\pdfeachlinedepth} \Whatever{dimen}
+}
+\fi
+
+\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}
+}
+
+% Currently it's only experimental, so don't really document it
+% (also not in pdftex-syntax.txt)
+%\Syntax {
+%\Tex {\pdfstrcmp} \Something{general text} \Something{general text} \Whatever{expandable}
+%}
+
+\Syntax {
+\Tex {\ifpdfabsnum} \Something{number} \Whatever{expandable}
+}
+
+\Syntax {
+\Tex {\ifpdfabsdim} \Something{dimen} \Whatever{expandable}
+}
+
+\Syntax {
+\Tex {\pdfuniformdeviate} \Something{number} \Whatever{expandable}
+}
+
+\Syntax {
+\Tex {\pdfnormaldeviate} \Whatever{expandable}
+}
+
+\Syntax {
+\Tex {\pdfmdfivesum} \Optional{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{offset \Something{number}} \Optional{length \Something{number}} \Something{general text}
+\Whatever{expandable}
+}
+
+\Syntax {
+\Tex {\pdfcolorstackinit} \Optional{page} \Optional{direct} \Something{general text}
+\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 {\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 {\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 {\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
+
+\subsubject{General definitions and syntax rules}
+
+\startpacked
+
+%%S NL
+%%S syntax rules:
+
+\Syntax {
+\Something{general text} \Means %
+  \Lbrace \Something{balanced text} \Rbrace
+}
+
+\Syntax {
+\Something{attr spec} \Means %
+  \Literal {attr} \Something{general text}
+}
+
+\Syntax {
+\Something{resources spec} \Means %
+  \Literal {resources} \Something{general text}
+}
+
+\Syntax {
+\Something{rule spec} \Means %
+  (\Literal {width} \Or \Literal {height} \Or \Literal {depth}) %
+  \Something{dimension} \Optional{\Something{rule spec}}
+}
+
+%\Syntax {\Something{object type spec} \Means
+%  \Optional{\Literal {stream}
+%  \Optional{\Something{attr spec}}} \Something{object contents}}
+
+\Syntax {
+\Something{object type spec} \Means %
+  \Literal{reserveobjnum}
+  \Or \Next %
+  \Optional{\Literal{useobjnum} \Something{number}} \Next %
+  \Optional{\Literal{stream} \Optional{\Something{attr spec}}} %
+  \Something{object contents}
+}
+
+\Syntax {
+\Something{annot type spec} \Means %
+  \Literal{reserveobjnum}
+  \Or \Next %
+  \Optional{\Literal{useobjnum} \Something{number}} %
+  \Optional{\Something{rule spec}} %
+  \Something{general text}
+}
+
+\Syntax {
+\Something{object contents} \Means %
+  \Something{file spec}
+  \Or \Something{general text}
+}
+
+\Syntax {
+\Something{xform attr spec} \Means %
+  \Optional{\Something{attr spec}} \Optional{\Something{resources spec}}
+}
+
+\Syntax {
+\Something{image attr spec} \Means %
+  \Optional{\Something{rule spec}} %
+  \Optional{\Something{attr spec}} %
+  \Optional{\Something{page spec}} %
+  \Optional{\Something{colorspace spec}} %
+  \Optional{\Something{pdf box spec}}
+}
+
+\Syntax {
+\Something{outline spec} \Means %
+  \Optional{\Something{attr spec}} %
+  \Something{action spec} %
+  \Optional{\Literal{count} \Something{number}} %
+  \Something{general text}
+}
+
+\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}
+}
+
+\Syntax {
+\Something{user-action spec} \Means %
+  \Something{general text}
+}
+
+%HE Check:
+\Syntax {
+\Something{goto-action spec} \Means %
+  \Something{numid}
+  \Or \Next \Optional{\Something{file spec}} \Something{nameid}
+  \Or \Next \Optional{\Something{file spec}} \Optional{\Something{page spec}} \Something{general text}
+  \Or \Next \Something{file spec} \Something{nameid} \Something{newwindow spec}
+  \Or \Next \Something{file spec} \Optional{\Something{page spec}} \Something{general text} \Something{newwindow spec}
+}
+
+\Syntax {
+\Something{thread-action spec} \Means %
+  \Optional{\Something{file spec}} \Something{numid}
+  \Or \Optional{\Something{file spec}} \Something{nameid}
+}
+
+\Syntax {
+\Something{open-action spec} \Means %
+  \Literal {openaction} \Something{action spec}
+}
+
+\Syntax {
+\Something{colorspace spec} \Means %
+  \Literal {colorspace} \Something{number}
+}
+
+\Syntax{
+\Something{pdf box spec} \Means %
+  \Literal{mediabox} %
+  \Or \Literal{cropbox} %
+  \Or \Literal{bleedbox} %
+  \Or \Literal{trimbox} %
+  \Or \Literal{artbox}
+}
+
+\Syntax{
+\Something{map spec} \Means %
+  \Lbrace \Optional{\Something{map modifier}} %
+  \Something{balanced text} \Rbrace
+}
+
+\Syntax{
+\Something{map modifier} \Means %
+  \Literal{+} \Or \Literal{=} \Or \Literal{-}
+}
+
+\Syntax {
+\Something{numid} \Means %
+  \Literal {num} \Something{number}
+}
+
+\Syntax {
+\Something{nameid} \Means %
+  \Literal {name} \Something{general text}
+}
+
+\Syntax {
+\Something{newwindow spec} \Means %
+  \Literal {newwindow} \Or \Literal {nonewwindow}
+}
+
+\Syntax {
+\Something{dest spec} \Means %
+  \Something{numid} \Something{dest type}
+  \Or \Something{nameid} \Something{dest type}
+}
+
+\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}
+}
+
+\Syntax {
+\Something{thread spec} \Means %
+  \Optional{\Something{rule spec}} %
+  \Optional{\Something{attr spec}} %
+  \Something{id spec}
+}
+
+\Syntax {
+\Something{id spec} \Means %
+  \Something{numid} \Or \Something{nameid}
+}
+
+\Syntax {
+\Something{file spec} \Means %
+  \Literal {file} \Something{general text}
+}
+
+\Syntax {
+\Something{page spec} \Means %
+  \Literal {page} \Something{number}
+}
+
+\Syntax {
+\Something{expand spec} \Means %
+  \Something{stretch} %
+  \Something{shrink} %
+  \Something{step} %
+  \Optional{\Literal{autoexpand}}
+}
+
+\Syntax {
+\Something{stretch} \Means %
+  \Something{number}
+}
+
+\Syntax {
+\Something{shrink} \Means %
+  \Something{number}
+}
+
+\Syntax {
+\Something{step} \Means %
+  \Something{number}
+}
+
+\Syntax {
+\Something{pre spec} \Means %
+  \Literal{pre}
+}
+
+\Syntax {
+\Something{pdfliteral spec} \Means %
+  \Literal{direct} \Or \Literal{page}
+}
+
+\Syntax {
+\Something{pdfspecial spec} \Means %
+  \Lbrace \Optional{\Something{pdfspecial id} \Optional{\Something{pdfspecial modifier}}} %
+  \Something{balanced text} \Rbrace
+}
+
+\Syntax {
+\Something{pdfspecial id} \Means %
+  \Literal{pdf:} \Or \Literal{PDF:}
+}
+
+\Syntax {
+\Something{pdfspecial modifier} \Means %
+  \Literal{direct:}
+}
+
+\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}
+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.
+
+%***********************************************************************
+
+\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.
+
+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}).
+
+%A warning to macro writers: The \PDFTEX-team reserves the namespaces
+%\type{\pdf*} and \type{\ptex*} for use by \PDFTEX; if you define macros
+%whose names start with \type{\pdf} or \type{\ptex}, you risk nameclashes
+%with new primitives introduced in future versions of \PDFTEX.
+
+General warning: many of these new primitives, for example
+\type{\pdfdest} and \type{\pdfoutline}, write their arguments directly
+to the \PDF\ output file (when producing \PDF), as \PDF\ string
+constants.  This means that {\em you} (or, more likely, the macros you
+write) must escape characters as necessary (namely \type{\}, \type{(},
+and \type{)}.  Otherwise, an invalid \PDF\ file may result.  The
+\type{hyperref} and \TEXINFO\ packages have code which may serve as
+a~starting point for implementing
+this, although it will certainly need to be adapted to any particular
+situation.
+
+%***********************************************************************
+
+\subsection{Document setup}
+
+\pdftexprimitive {\Syntax {\Tex {\pdfoutput} \Whatever{integer}}}
+
+\bookmark{\type{\pdfoutput}}
+
+This parameter specifies whether the output format should be \DVI\ or
+\PDF. A~positive value means \PDF\ output, otherwise (default 0) one gets
+\DVI\ output.  This primitive is the only one that must be set to produce
+\PDF\ output (unless the commandline option \type{-output-format=pdf}
+is used); all other primitives are optional.  This parameter cannot be
+specified {\em after} shipping out the first page.  In other words, if
+we want \PDF\ output, we have to set \type{\pdfoutput} before \PDFTEX\
+ships out the first page.
+
+When \PDFTEX\ starts complaining about specials, one can be rather sure
+that a~macro package is not aware of the \PDF\ mode. A~simple way of
+making macros aware of \PDFTEX\ in \PDF\ or \DVI\ mode is:
+
+\starttyping
+\ifx\pdfoutput\undefined \csname newcount\endcsname\pdfoutput \fi
+\ifcase\pdfoutput DVI CODE \else PDF CODE \fi
+\stoptyping
+
+Using the \type{ifpdf.sty} file, which works with both \LATEX\ and plain
+\TeX, is a~cleaner way of doing this.  Historically, the simple test
+\type{\ifx\pdfoutput\undefined} was defined; but nowadays, the \PDFTEX\
+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}}}
+
+\bookmark{\type{\pdfminorversion}}
+
+This primitive sets the \PDF\ version of the generated file and the latest
+allowed \PDF\ version of included \PDF{}s. \Eg, \type{\pdfminorversion=3} tells
+\PDFTEX\ to set the \PDF\ version to 1.3 and allows only included \PDF\ files
+with versions numbers up to 1.3. The default for \type{\pdfminorversion} is 4,
+producing files with \PDF\ version 1.4. If specified, this primitive must
+appear before any data is to be written to the generated \PDF\ file, so you
+should put it at the very start of your files. The command has been introduced
+in \PDFTEX\ 1.30.0 as a~shortened synonym of \type{\pdfoptionpdfminorversion}
+command, that is obsolete by now.
+
+\pdftexprimitive {\Syntax {\Tex {\pdfcompresslevel} \Whatever{integer}}}
+
+\bookmark{\type{\pdfcompresslevel}}
+
+This integer parameter specifies the level of {\em stream} compression
+(text, in||line graphics, and embedded \PNG\ images (only if they are
+un- and re||compressed during the embedding process); all done by the
+\type{zlib} library). Zero means no compression, 1~means fastest, 9~means
+best, 2..8 means something in between. A~value outside this range will
+be adjusted to the nearest meaningful value. This parameter is read
+each time \PDFTEX\ starts a~stream. Setting \type{\pdfcompresslevel=0}
+is great for \PDF\ stream debugging.
+
+\pdftexprimitive {\Syntax {\Tex {\pdfobjcompresslevel} \Whatever{integer}}}
+
+\bookmark{\type{\pdfobjcompresslevel}}
+
+This integer parameter controls the compression of {\em non-stream}
+objects. In the \PDF-1.4 specification these objects still had to go into
+the \PDF\ file as clear text, uncompressed. The \PDF-1.5 specification
+now allows to collect non-stream objects as ``compressed objects'' into
+``object stream'' objects (\type{/Type /ObjStm}, see \PDF\ Ref.\ 5th~ed.,
+sect.~3.4.6). At the \PDF\ file end instead of the object table then
+an \type{/XRef} cross-reference stream is written out. This results in
+considerably smaller \PDF\ files, particularly if lots of annotations
+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
+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
+writing is disabled. The \type{\pdfobjcompresslevel} value is clipped
+to the range 0..3. Using values outside this range is not recommended
+(for future extension).
+
+The \type{\pdfobjcompresslevel} settings have the following effects:
+When set to~0, no object streams are generated at all. When set to~1,
+all non-stream objects are compressed with the exception of any objects
+coming with embedded \PDF\ files (``paranoid'' mode, to avoid yet unknown
+problems), and also the \type{/Info} dictionary is not compressed for
+clear-text legibility. When set to~2, also all non-stream objects coming
+with embedded \PDF\ files are compressed, but the \type{/Info} dictionary
+is still not compressed. Finally, when set to~3, all non-stream objects
+are compressed, including the \type{/Info} dictionary (this means that
+the \type{/Info} can't be read as clear text any more). If object streams
+are to be used, currently \type{\pdfobjcompresslevel=2} is recommended,
+
+\description{Caveat:} \PDF\ files generated with object streams enabled
+can't be read with (old) \PDF\ viewers that don't understand \PDF-1.5
+files. For widest distribution and unknown audience, don't activate
+object stream writing. The \PDF-1.5 standard describes also a~hybrid
+object compression mode that gives some backward compatibility, but this
+is currently not implemented, as \PDF-1.5 seems to be rather quickly
+adopted by modern \PDF\ viewers. Also not implemented is the optional
+\type{/Extends} key.
+
+\pdftexprimitive {\Syntax {\Tex {\pdfdecimaldigits} \Whatever{integer}}}
+
+\bookmark{\type{\pdfdecimaldigits}}
+
+This integer parameter specifies the numeric accuracy of real coordinates as written
+to the \PDF\ file. It gives the maximal number of decimal digits after the
+decimal point. Valid values are in range 0..4. A~higher value means
+more precise output, but also results in a~larger file size and more
+time to display or print. In most cases the optimal value is~2. This
+parameter does not influence the precision of numbers used in raw \PDF\ code,
+like that used in \type{\pdfliteral} and annotation action specifications;
+also multiplication items (\eg\ scaling factors)
+are not affected and are always output with best precision.
+This parameter is read when \PDFTEX\ writes a~real number to 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}}}
+
+\bookmark{\type{\pdfhorigin}}
+
+This parameter can be used to set the horizontal offset the output box
+from the top left corner of the page. A~value of 1~inch corresponds to the
+normal \TEX\ offset. This parameter is read when \PDFTEX\ starts shipping
+out a~page to the \PDF\ output.
+
+For standard purposes, this parameter should always be kept at
+1~true inch.  If you want to shift text on the page, use \TEX's
+own \type{\hoffset} primitive.  To avoid surprises, after global
+magnification has been changed by the \type{\mag} primitive, the
+\type{\pdfhorigin} parameter should still be 1~true inch, \eg\
+by typing \type{\pdfhorigin=1 true in} after issuing the \type{\mag}
+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}}}
+
+\bookmark{\type{\pdfvorigin}}
+
+This parameter is the vertical companion of \type{\pdfhorigin}, and the
+notes above regarding \type{\mag} and true dimensions apply. Also keep
+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}}}
+
+\bookmark{\type{\pdfpagewidth}}
+
+This dimension parameter specifies the page width of the \PDF\ output
+(the screen, the paper, etc.). \PDFTEX\ reads this parameter when it
+starts shipping out a~page.  After magnification has been changed by
+the \type{\mag} primitive, check that this parameter reflects the wished
+true page width.
+
+If the value is set to zero, the page width is calculated as
+$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}}}
+
+\bookmark{\type{\pdfpageheight}}
+
+Similar to the previous item, this dimension parameter specifies the
+page height of the \PDF\ output. If set to zero, the page height will
+be calculated analogously to the above. After magnification has been
+changed by the \type{\mag} primitive, check that this parameter reflects
+the wished true page height.
+
+\subsection{The document info and catalog}
+
+\pdftexprimitive {\Syntax {\Tex {\pdfinfo} \Something{general text}}}
+
+\bookmark{\type{\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}.
+
+\type{/CreationDate} and \type{/ModDate} are expressed in the form
+\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.
+
+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.
+
+An example of the use of \type{\pdfinfo} is:
+
+\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) }
+\stopesctyping
+
+\pdftexprimitive {\Syntax {\Tex {\pdfcatalog} \Something{general text}
+\Optional{\Something{open-action spec}}}}
+
+\bookmark{\type{\pdfcatalog}}
+
+Similar to the document info section is the document catalog, where keys
+are \type{/URI}, which provides the base \URL\ of the document, and \type
+{/PageMode}, which determines how the \PDF\ viewer displays the document
+on startup. The possibilities for the latter are explained in \in {Table}
+[pagemode]:
+
+\startbuffer
+\starttabulate[|l|l|]
+\HL
+\NC \bf value        \NC \bf meaning                            \NC\NR
+\HL
+\NC \tt /UseNone     \NC neither outline nor thumbnails visible \NC\NR
+\NC \tt /UseOutlines \NC outline visible                        \NC\NR
+\NC \tt /UseThumbs   \NC thumbnails visible                     \NC\NR
+\NC \tt /FullScreen  \NC full||screen mode                      \NC\NR
+\HL
+\stoptabulate
+\stopbuffer
+
+\placetable
+  [here][pagemode]
+  {Supported \type{/PageMode} values.}
+  {\getbuffer}
+
+In full||screen mode, there is no menu bar, window controls, nor any other
+window present. The default setting is \type{/UseNone}.
+
+The \Something{openaction} is the action provided when opening the
+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}}}
+
+\bookmark{\type{\pdfnames}}
+
+This primitive inserts the \Something{general text} to the \type
+{/Names} array. The text must
+conform to the specifications as laid down in the \PDFReference,
+otherwise the document can be invalid.
+
+\pdftexprimitive {\Syntax {\Tex {\pdftrailer} \Something{general text}}}
+
+\bookmark{\type{\pdftrailer}}
+
+This command puts its argument text verbatim into the file trailer
+dictionary. \introduced{1.11a}
+
+%***********************************************************************
+
+\subsection{Fonts}
+
+\pdftexprimitive {\Syntax {\Tex {\pdfpkresolution} \Whatever{integer}}}
+
+\bookmark{\type{\pdfpkresolution}}
+
+This integer parameter specifies the default resolution of embedded \PK\
+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}}}}
+
+\bookmark{\type{\pdffontexpand}}
+
+This extension to \TEX's font definitions controls a~\PDFTEX\ automatism
+called {\em font expansion}. We describe this by an example:
+
+\starttyping
+\font\somefont=sometfm at 10pt
+\pdffontexpand\somefont 30 20 10 autoexpand
+\pdfadjustspacing=2
+\stoptyping
+
+The \type{30 20 10} means this: \quotation {hey \TEX, when line breaking
+is going badly, you may stretch the glyphs from this font as much as
+3\,\% or shrink them as much as 2\,\%}. For practical reasons \PDFTEX\
+uses discrete expansion steps, in this example, 1\,\%. Roughly spoken, the
+trick is as follows. Consider a~text typeset in triple column mode. When
+\TEX\ cannot break a~line in the appropriate way, the unbreakable parts
+of the word will stick into the margin. When \PDFTEX\ notes this, it
+will try to scale (shrink) the glyphs in that line using fixed steps,
+until the line fits. When lines are too spacy, the opposite happens:
+\PDFTEX\ starts scaling (stretching) the glyphs until the white space
+gaps is acceptable. This glyph stretching and shrinking is called
+{\em font expansion}. To enable font expansion, don't forget to set
+\type{\pdfadjustspacing} to a~value greater than zero.
+
+There are two different modes for font expansion:
+
+First, if the \type{autoexpand} option is there --- 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
+ignored), as \PDFTEX\ generates expanded copies of the unexpanded \TFM\
+data structures and keeps them in its memory. Since \PDFTEX~1.40.0 the
+\type{autoexpand} mode happens within the page stream by modification of
+the text matrix (\PDF\ operator ``\type{Tm}''), and not anymore on font
+file level, giving the advantage that it now works not only with Type1
+but also with TrueType and OpenType fonts (and even without embedding
+a~font file; but that's not recommended). In this mode \PDFTEX\ requires
+only unexpanded font files.
+
+Second, if the \type{autoexpand} option is missing, setting up font
+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\,\%
+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
+for each expansion value an individually crafted font file with expanded
+glyphs. Depending on how these glyphs are generated, this might give
+slightly better glyph forms than the rather simple glyph stretching
+used in \type{autoexpand mode}. The drawback is that several font
+files will be embedded in the \PDF\ output for each expanded font,
+leading to significantly larger \PDF\ files than in \type{autoexpand}
+mode. For moderate expansion values going without \type{autoexpand}
+mode is not worth the trouble.
+
+The font expansion mechanism is inspired by an optimization first
+introduced by Prof.~Hermann Zapf, which in itself goes back to
+optimizations used in the early days of typesetting: use different
+glyphs to optimize the grayness of a~page. So, there are many, slightly
+different~a's, e's, etc. For practical reasons \PDFTEX\ does not use
+such huge glyph collections; it uses horizontal scaling instead. This is
+sub||optimal, and for many fonts, possibly offensive to the design. But,
+when using \PDF, it's not illogical: \PDF\ viewers use so||called
+Multiple Master fonts when no fonts are embedded and|/|or can be found
+on the target system. Such fonts are designed to adapt their design to
+the different scaling parameters. It is up to the user to determine
+to what extent mixing slightly remastered fonts can be used without
+violating the design. Think of an~O: when geometrically stretched, the
+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}}}
+
+\bookmark{\type{\pdfadjustspacing}}
+
+This primitive provides a~switch for enabling font expansion. By default,
+\type{\pdfadjustspacing} is set to~0; then font expansion is disabled,
+so that the \PDFTEX\ output is identical to that from the original \TEX\
+engine.
+
+Font expansion can be activated in two modes. When
+\type{\pdfadjustspacing} is set to~1, font expansion is applied {\em
+after} \TEX's normal paragraph breaking routines have broken the paragraph
+into lines. In this case, line breaks are identical to standard \TEX\
+behaviour.
+
+When set to~2, the width changes that are the result of stretching and
+shrinking are taken into account {\em while} the paragraph is broken into
+lines. In this case, line breaks are likely to be different from those of
+standard \TEX. In fact, paragraphs may even become longer or shorter.
+
+Both alternatives require a~collection of \TFM\ files that are
+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} \Whatever{integer}}}
+
+\bookmark{\type{\efcode}}
+
+We didn't yet tell 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
+setting from the \type{\pdffontexpand} primitive. The syntax is similar
+to \type{\sfcode} (but with the \Something{font} required), and it
+defaults to~1000, meaning 100\,\% expandability. The given integer value
+is clipped to the range 0..1000, corresponding to a~usable expandability
+range of 0..100\,\%. Example:
+
+\starttyping
+\efcode\somefont`A=800
+\efcode\somefont`O=0
+\stoptyping
+
+Here an~A may stretch or shrink only by 80\,\% of the current expansion
+value for that font, and expansion for the~O is disabled. The actual
+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}}}
+
+\bookmark{\type{\pdfprotrudechars}}
+
+Yet another way of optimizing paragraph breaking is to let certain
+characters move into the margin (`character protrusion'). When
+\type{\pdfprotrudechars=1}, the glyphs qualified as such will make
+this move when applicable, without changing the line-breaking. When
+\type{\pdfprotrudechars=2} (or greater), character protrusion will
+be taken into account while considering breakpoints, so line-breaking
+might be changed. This qualification and the amount of shift are set by
+the primitives \type{\rpcode} and \type{\lpcode}. Character protrusion
+is disabled when \type{\pdfprotrudechars=0} (or negative).
+
+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} \Whatever{integer}}}
+
+\bookmark{\type{\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},
+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:
+
+\starttyping
+\rpcode\somefont`,=200
+\rpcode\somefont`-=150
+\stoptyping
+
+Here the comma may shift by 0.2\,em into the margin and the hyphen by
+0.15\,em. All these small bits and pieces will help \PDFTEX\ to give
+you better paragraphs (use \type{\rpcode} judiciously; don't overdo it).
+
+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}
+\Whatever{integer}}}
+
+\bookmark{\type{\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}}}
+
+\bookmark{\type{\leftmarginkern}}
+
+The \Tex{\leftmarginkern} \Something{box number} primitive expands to the
+width of the margin kern at the left side of the horizontal list stored
+in \Tex{\box} \Something{box number}. The expansion string includes the
+unit \type{pt}. \Eg, when the left margin kern of \type{\box0} amounts
+to $-$10\,pt, \type{\leftmarginkern0} will expand to \type{-10pt}.
+A~similar primitive \type{\rightmarginkern} exists for the right margin.
+\introduced{1.30.0}
+
+These are auxiliary primitives to make character protrusion
+more versatile. When using the \TEX\ primitive \type{\unhbox} or
+\type{\unhcopy}, the margin kerns at either end of the unpackaged
+hbox will be removed (\eg\ to avoid weird effects if several
+hboxes are unpackaged behind each other into the same horizontal
+list). These \type{\unhbox} or \type{\unhcopy} are often used together
+with \type{\vsplit} for dis- and re||assembling of paragraphs, \eg\ to
+add line numbers. Paragraphs treated like this do not show character
+protrusion by default, as the margin kerns have been removed during the
+unpackaging process.
+
+The \type{\leftmarginkern} and \type{\rightmarginkern} primitives allow
+to access the margin kerns and store them away before unpackaging the
+hbox. \Eg\, the following code snipplet restores margin kerning of
+a~horizontal list stored in \type{\box\testline}, resulting in a~hbox with
+proper margin kerning (which is then done by ordinary kerns).
+
+\starttyping
+\dimen0=\leftmarginkern\testline
+\dimen1=\rightmarginkern\testline
+\hbox to\hsize{\kern\dimen0\unhcopy\testline\kern\dimen1}
+\stoptyping
+
+\pdftexprimitive {\Syntax {\Tex {\rightmarginkern} \Something{box number} \Whatever{expandable}}}
+
+\bookmark{\type{\rightmarginkern}}
+
+The \Tex{\rightmarginkern} \Something{box number} primitive expands to
+the width of the margin kern at the right side of the horizontal list
+stored in \Tex{\box} \Something{box number}. See \type{\leftmarginkern}
+for more details.
+\introduced{1.30.0}
+
+\pdftexprimitive {\Syntax {\Tex {\pdffontattr} \Something{font} \Something{general text}}}
+
+\bookmark{\type{\pdffontattr}}
+
+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.
+
+\pdftexprimitive {\Syntax {\Tex {\pdffontname} \Something{font} \Whatever
+{expandable}}}
+
+\bookmark{\type{\pdffontname}}
+
+In \PDF\ files produced by \PDFTEX\ one can recognize a~font resource
+by the prefix~\type{/F} followed by a~number, for instance \type{/F12}
+or \type{/F54}.  For a~given \TEX\ \Something{font}, this primitive
+expands to the number from the corresponding font resource name.
+\Eg, if \type{/F12} corresponds to some \TEX\ font \type{\foo}, the
+\type{\pdffontname\foo} expands to the number~\type{12}.
+
+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}}}
+
+\bookmark{\type{\pdffontobjnum}}
+
+This command is similar to \type{\pdffontname}, but it returns the
+\PDF\ object number of the font dictionary instead of the number from
+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
+access to all the font resources used in the document.
+
+\pdftexprimitive {\Syntax {\Tex {\pdffontsize} \Something{font} \Whatever
+{expandable}}}
+
+\bookmark{\type{\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}}}
+
+\bookmark{\type{\pdfincludechars}}
+
+This command causes \PDFTEX\ to treat the characters in \Something{general
+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}}}
+
+\bookmark{\type{\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}}}
+
+\bookmark{\type{\pdfmapfile}}
+
+This primitive is used for reading a~font map file consisting of
+one or more font map lines. The name of the map file is given in
+the \Something{map spec} together with an optional leading modifier
+character. If no \type{\pdfmapfile} primitive is given, the default map
+file \filename{pdftex.map} will be read by \PDFTEX. There is a~companion
+primitive \type{\pdfmapline} that allows to scan single map lines;
+its map line argument has the same syntax as the map lines from a~map
+file. Both primitives can be used concurrently. The \type{\pdfmapfile}
+primitive is fast for reading external bulk font map information (many
+map lines collected in a~map file), whereas the \type{\pdfmapline} allows
+to put the font map information for individual \TeX\ fonts right into
+the \TeX\ source or a~style file. In any case the map line information
+is scanned by \PDFTEX, and in the most common case the data are put into
+a~fresh internal map entry data structure, which is then consulted once
+a~font is called.
+
+Normally there is no need for the \PDFTEX\ user to bother about the
+\type{\pdfmapfile} or \type{\pdfmapline} primitives, as the main \TEX\
+distributions provide nice helper tools that automatically assemble
+the default font map file. Prominent tool examples are the scripts
+\type{updmap} and \type{updmap-sys} coming with \TEXLIVE\ and \TETEX.
+If your map file isn't in the current directory (or a~standard system
+directory), you will need to set the \type{TEXFONTMAPS} variable (in
+\WEBC) or give an explicit path so that it will be found.
+
+When the \type{\pdfmapfile} or \type{\pdfmapline} primitive is read
+by \PDFTEX, the argument (map file or map line) will be processed
+{\em immediately}, and the internal map entry database is updated.
+The operation mode of the \type{\pdfmapfile} and \type{\pdfmapline}
+primitives is selected by an optional modifier character (\type{+},
+\type{=}, \type{-}) in front of the {\em tfmname} field. This modifier
+defines how the individual map lines are going to be handled, and how
+a~collision between an already registered map entry and a~newer one is
+resolved; either ignoring a~later entry, or replacing or deleting an
+existing entry. But in any case, map entries of fonts already in use
+are kept untouched. Here are two examples:
+
+\starttyping
+\pdfmapfile{+myfont.map}
+\pdfmapline{+ptmri8r Times-Italic <8r.enc <ptmri8a.pfb}
+\stoptyping
+
+When no modifier character is given (\eg\ \type{\pdfmapfile{foo.map}}
+or \type{\pdfmapline{phvr8r Helvetica}}) and there hasn't already been
+any call of one of these primitives before, then the default map file
+\filename{pdftex.map} will {\em not} be read in. Apart from this the
+given map file will be processed similarly as with a~\type{+} modifier:
+duplicate later map entries within the file are ignored and a~warning is
+issued. This means, that you can block reading of the default map file
+also by an empty \type{\pdfmapfile{}} or \type{\pdfmapline{}} early in
+the \TeX\ file. When the default map file is large but you don't need it
+anyway, these command variants might considerably speed up the \PDFTEX\
+startup process.
+
+If a~modifier is given, the mechanism is so that before reading the
+items given as arguments to \type{\pdfmapfile} or \type{\pdfmapline}
+the default map file will be read first --- if this hasn't already
+been done or been prevented by the above blocking cases. This should
+be mostly compatible with the traditional behaviour. If you want to add
+support for a~new font through an additional font map file while keeping
+all the existing mappings, don't use the primitive versions without
+modifier, but instead type either \type{\pdfmapfile{+myfont.map}} or
+\type{\pdfmapfile{=myfont.map}}, as described below.
+
+\type{\pdfmapfile {+foo.map}} reads the file \filename{foo.map}; duplicate
+later map entries within the file are ignored and a~warning is issued.
+
+\type{\pdfmapfile {=foo.map}} reads the file \filename{foo.map};
+matching map entries in the database are replaced by new entries from
+\filename{foo.map} (if they aren't already in use).
+
+\type{\pdfmapfile {-foo.map}} reads the file \filename{foo.map}; matching
+map entries are deleted from the database (if not yet in use).
+
+If you want to use a~base map file name other than \type{pdftex.map},
+or change its processing options through a~\PDFTEX\ format, you can do
+this by appending the \type{\pdfmapfile} command to the \type{\everyjob{}}
+token list for the \type{-ini} run, \eg:
+
+\starttyping
+\everyjob\expandafter{\the\everyjob\pdfmapfile{+myspecial.map}}
+\dump
+\stoptyping
+
+This would always read the file \type{myspecial.map} after the default
+\type{pdftex.map} file.
+
+\pdftexprimitive {\Syntax {\Tex {\pdfmapline} \Something{map spec}}}
+
+\bookmark{\type{\pdfmapline}}
+
+Similar to \type{\pdfmapfile}, but here you can give a~single
+map line (like the ones in map files) as an argument. The optional modifiers
+(\type{+-=}) have the same effect as with \type{\pdfmapfile}; see also
+the description above.  Example:
+
+\starttyping
+\pdfmapline{+ptmri8r Times-Italic <8r.enc <ptmri8a.pfb}
+\stoptyping
+
+This primitive (especially the \type{\pdfmapline{=...}} variant) is useful
+for temporary quick checks of a~new font map entry during development,
+before finally putting it into a~map file.
+
+\type{\pdfmapline {}} like \type{\pdfmapfile {}} blocks reading
+of the default map file, if it comes early enough in the \TeX\
+input. \introduced{1.20a}
+
+\pdftexprimitive {\Syntax {\Tex {\pdftracingfonts} \Whatever{integer}}}
+
+\bookmark{\type{\pdftracingfonts}}
+
+This integer parameter specifies the level of verbosity for info about
+expanded fonts given in the log, \eg\ when \type{\tracingoutput=1}.
+If \type{\pdftracingfonts=0}, which is the default, the log shows the
+actual non-zero signed expansion value for each expanded letter within
+brackets, \eg:
+
+\starttyping
+...\xivtt (+20) t
+\stoptyping
+
+If \type{\pdftracingfonts=1}, also the name of the \TFM\ file is listed,
+together with the font size, \eg:
+
+\starttyping
+...\xivtt (cmtt10+20@14.0pt) t
+\stoptyping
+
+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}}}
+
+\bookmark{\type{\pdfmovechars}}
+
+Since \PDFTEX\ version 1.30.0 the primitive \type{\pdfmovechars} is obsolete,
+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}}}
+
+\bookmark{\type{\pdfpkmode}}
+
+The \type{\pdfpkmode} is a~token register that sets the \METAFONT\ mode for
+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}}}
+
+\bookmark{\type{\pdfnoligatures}}
+
+This diables all ligatures in the loaded font \Something{font}.
+\introduced{1.30.0}
+
+%***********************************************************************
+
+\subsection{\PDF\ objects}
+
+\pdftexprimitive {\Syntax {\Tex {\pdfobj} \Something{object type spec}}}
+
+\bookmark{\type{\pdfobj}}
+
+This command creates a~raw \PDF\ object that is written to the \PDF\ file as
+\type{1 0 obj} \unknown\ \type{endobj}. The object is written to \PDF\ output as
+provided by the user. When \Something{object type spec} is not given, \PDFTEX\
+does not any longer create a~dictionary object with contents \Something{general text},
+as it was in the past.
+
+When however \Something{object type spec} is given as \Something{attr spec}
+\Literal{stream}, the object will be created as a~stream with contents
+\Something{general text} and additional attributes in \Something{attr
+spec}\unkern.
+
+When \Something{object type spec} is given as \Something{attr spec}
+\Literal{file}, then the \Something{general text} will be treated as a~file
+name and its contents will be copied into the stream contents.
+
+When \Something{object type spec} is given as \type{reserveobjnum},
+just a~new object number is reserved. The number of the reserved object
+is accessible via \type{\pdflastobj}. The object can later be filled
+with contents by \Syntax{\Tex{\pdfobj} \Literal{useobjnum}
+\Something{number} \Lbrace\Something{balanced text}\Rbrace}.
+But the reserved object number can already be be used before by other
+objects, which provides a~forward||referencing mechanism.
+
+The object is kept in memory and will be written to the \PDF\ output only
+when its number is referred to by \type{\pdfrefobj} or when \type{\pdfobj}
+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}}}
+
+\bookmark{\type{\pdflastobj}}
+
+This command returns the object number of the last object created by \type
+{\pdfobj}.
+
+\pdftexprimitive {\Syntax {\Tex {\pdfrefobj} \Something{object number}}}
+
+\bookmark{\type{\pdfrefobj}}
+
+This command appends a~whatsit node to the list being built. When the whatsit
+node is searched at shipout time, \PDFTEX\ will write the object
+\Something{object number}
+to the \PDF\ output if it has not been written yet.
+
+%***********************************************************************
+
+\subsection{Page and pages objects}
+
+\pdftexprimitive {\Syntax {\Tex {\pdfpagesattr} \Whatever{tokens}}}
+
+\bookmark{\type{\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.
+
+% /MediaBox is not a good example, since will never take an effect
+
+\starttyping
+\pdfpagesattr
+  { /Rotate 90                % rotate all pages by 90 degrees
+    /CropBox [0 0 612 792] }  % the crop size of all pages (in bp)
+\stoptyping
+
+\pdftexprimitive {\Syntax {\Tex {\pdfpageattr} \Whatever{tokens}}}
+
+\bookmark{\type{\pdfpageattr}}
+
+This is similar to \type{\pdfpagesattr}, but has priority over it.
+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}}}
+
+\bookmark{\type{\pdfpageref}}
+
+This primitive expands to the number of the page object that contains the
+dictionary for page \Something{page number}. If the page \Something{page
+number} does not exist, a~warning will be issued, a~fresh unused \PDF\
+object will be generated, and \type{\pdfpageref} will expand to that
+object number.
+
+\Eg, if the dictionary for page~5 of the \TEX\ document is contained in
+\PDF\ object no.~18, \tex{pdfpageref5} expands to the number 18.
+
+%***********************************************************************
+
+\subsection{Form XObjects}
+
+The next three primitives support a~\PDF\ feature called \quote {object
+reuse} in \PDFTEX. The idea is first to create a~`form XObject' in
+\PDF. The content of this object corresponds to the content of a~\TEX\
+box; it can contain pictures and references to other form XObjects
+as well. After creation, the form XObject can be used multiple times
+by simply referring to its object number. This feature can be useful
+for large documents with many similar elements, as it can reduce the
+duplication of identical objects.
+
+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}}}
+
+\bookmark{\type{\pdfxform}}
+
+This command creates a~form XObject corresponding to the contents of the
+box \Something{box number}. The box can contain other raw objects, form
+XObjects, or images as well. It can however {\em not} contain annotations
+because they are laid out on a~separate layer, are positioned absolutely,
+and have dedicated housekeeping. \type{\pdfxform} makes the box void,
+as \type{\box} does.
+
+When \Something{attr spec} is given, the text will be written
+as additional attribute into the form XObject dictionary. The
+\Something{resources spec} is similar, but the text will be added
+to the resources dictionary of the form XObject. The text given by
+\Something{attr spec} or \Something{resources spec} is written before
+other entries of the form dictionary and|/|or the resources dictionary
+and takes priority over later ones.
+
+\pdftexprimitive {\Syntax {\Tex {\pdfrefxform} \Something{object number}}}
+
+\bookmark{\type{\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}.
+
+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}}
+
+\bookmark{\type{\pdflastxform}}
+
+The object number of the most recently created form XObject is accessible
+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}}}
+
+\bookmark{\type{\pdfxformname}}
+
+In \PDF\ files produced by \PDFTEX\ one can recognize a~form Xobject by
+the prefix~\type{/Fm} followed by a~number, for instance \type{/Fm2}.
+For a~given form XObject number, this primitive expands to the number
+in the corresponding form XObject name. \Eg, if \type{/Fm2} corresponds
+to some form XObject with object number 7, the \type{\pdfxformname7}
+expands to the number~\type{2}. \introduced{1.30.0}
+
+%***********************************************************************
+
+\subsection{Graphics inclusion}
+
+\PDF\ provides a~mechanism for embedding graphic and textual objects: form
+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}
+  \Optional{\Something{rule spec}}
+  \Optional{\Something{attr spec}}
+  \Optional{\Something{page spec}}
+  \Optional{\Something{colorspace spec}}
+  \Optional{\Something{pdf box spec}}
+  \Something{general text}
+}}
+
+\bookmark{\type{\pdfximage}}
+
+This command creates an image object. The dimensions of the image can be
+controlled via \Something{rule spec}\unkern. The default values are zero for depth
+and \quote {running} for height and width. If all of them are given, the
+image will be scaled to fit the specified values. If some (but not
+all) are given, the rest will be set to a~value corresponding to the
+remaining ones so as to make the image size to yield the same proportion of
+$width : (height+depth)$ as the original image size, where depth is treated
+as zero. If none are given then the image will take its natural size.
+
+An image inserted at its natural size often has a~resolution of \type
+{\pdfimageresolution} (see below) given in dots per inch in the output file,
+but some images may contain data specifying the image resolution, and in such
+a~case the image will be scaled to the correct resolution. The dimensions of
+an image can be accessed by enclosing the \type{\pdfrefximage} command to
+a~box and checking the dimensions of the box:
+
+\starttyping
+\setbox0=\hbox{\pdfximage{somefile.png}\pdfrefximage\pdflastximage}
+\stoptyping
+
+Now we can use \type{\wd0} and \type{\ht0} to question the natural size of
+the image as determined by \PDFTEX. When dimensions are specified before the
+\type{{somefile.png}}, the graphic is scaled to fit these. Note that, unlike
+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
+\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
+file start, which gets precedence over the file name extension. This
+gives a~certain degree of fault tolerance, if the file name extension
+is stated wrongly.
+
+Similarly to \type{\pdfxform}, the optional text given by \Something{attr
+spec} will be written as additional attributes of the image before
+other keys of the image dictionary. One should be aware, that slightly
+different type of \PDF\ object is created while including \PNG, \JPEG,
+or \JBIG2\ bitmaps and \PDF\ images.
+
+While working with \PDF\ or \JBIG2\ images, \Something{page spec}
+allows to decide which page of the document is to be included;
+the \Something{page spec} is irrelevant for the other two image
+formats. Starting from \PDFTEX\ 1.11 one may also decide in the \PDF\
+image case, which page box of the image is to be treated as a~final
+bounding box. If \Something{pdf box spec} is present, it overrides the
+default behaviour specified by the \type{\pdfforcepagebox} parameter. This
+option is irrelevant for non||\PDF\ inclusions.
+
+Starting from \PDFTEX\ 1.21, \type{\pdfximage} command supports
+\type{colorspace} keyword followed by an object number (user||defined
+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}}}
+
+\bookmark{\type{\pdfrefximage}}
+
+The image is kept in memory and will be written to the \PDF\ output only when
+its number is referred to by \type{\pdfrefximage} or \type{\pdfximage} is
+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
+written yet.
+
+\pdftexprimitive {\Syntax {\Tex {\pdflastximage} \Whatever{read||only
+integer}}}
+
+\bookmark{\type{\pdflastximage}}
+
+The number of the most recently created XObject image is accessible via \type
+{\pdflastximage}.
+
+\pdftexprimitive {\Syntax {\Tex {\pdflastximagepages} \Whatever{read||only
+integer}}}
+
+\bookmark{\type{\pdflastximagepages}}
+
+This read||only register returns the highest page number from a~file
+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}}}
+
+\bookmark{\type{\pdfimageresolution}}
+
+The integer \type{\pdfimageresolution} parameter (unit: dots per
+inch, dpi) is a~last resort value, used only for bitmap (\JPEG, \PNG,
+\JBIGTWO) images, but not for \PDF{}s. The priorities are as follows:
+Often one image dimension (\type{width} or \type{height}) is stated
+explicitely in the \TEX\ file. Then the image is properly scaled so
+that the aspect ratio is kept. If both image dimensions are given,
+the image will be stretched accordingly, whereby the aspect ratio might
+get distorted. Only if no image dimension is given in the \TEX\ file,
+the image size will be calculated from its width and height in pixels,
+using the $x$ and $y$ resolution values normally contained in the image
+file. If one of these resolution values is missing or weird (either
+$<$~0 or $>$~65535), the \type{\pdfimageresolution} value will be used
+for both $x$ and $y$ resolution, when calculating the image size. And
+if the \type{\pdfimageresolution} is zero, finally a~default resolution
+of 72\,dpi would be taken. The \type{\pdfimageresolution} is read when
+\PDFTEX\ creates an image via \type{\pdfximage}. The given value is
+clipped to the range 0..65535\,[dpi].
+
+Currently this parameter is used particularly for calculating the
+dimensions of \JPEG\ images in \EXIF\ format (unless at least one
+dimension is stated explicitely); the resolution values coming with \EXIF\
+files are currently ignored.
+
+\pdftexprimitive {\Syntax {\Tex {\pdfforcepagebox} \Whatever{integer}}}
+
+\bookmark{\type{\pdfforcepagebox}}
+
+%- It is now possible to specify the pdf page box to use when including pdfs.
+%  The syntax has been extended:
+%    \pdfximage [<image attr spec>] <general text>           (h, v, m)
+%    <image attr spec> --> [<rule spec>] [<attr spec>] [<page spec>] [<pdf box spec>]
+%    <pdf box spec> --> mediabox|cropbox|bleedbox|trimbox|artbox
+%  The default is cropbox (which defaults to mediabox), to be compatible with
+%  previous versions of pdfTeX.
+%    The page box specified at \pdfximage can be globally overridden with the
+%  config parameter always_use_pdfpagebox and the command
+%  \pdfoptionalwaysusepdfpagebox <integer>, where 0 is the default (use whatever
+%  is specified with \pdfximage), 1 is media, 2 is crop, 3 is bleed, 4 is trim
+%  and 5 is artbox. This can only be set once per object, i.\,e.\ the value used at
+%  \pdfximage is remembered.
+%    See the PDF Reference for an explanation of the boxes.
+
+When \PDF\ files are included, the command \type{\pdfximage} allows the selection
+of which \PDF\ page box to use in the optional field \Something{image attr
+spec}\unkern.  The integer primitive \type{\pdfforcepagebox} allows to globally
+override this choice by giving them one of the following values: (1) media box,
+(2) crop box, (3) bleed box, (4) trim box, and (5) artbox. The command is
+available starting from \PDFTEX\ 1.30.0, as a~shortened synonym of obsolete
+\type{\pdfoptionalwaysusepdfpagebox} instruction.
+
+\pdftexprimitive {\Syntax {\Tex {\pdfinclusionerrorlevel} \Whatever{integer}}}
+
+\bookmark{\type{\pdfinclusionerrorlevel}}
+
+This controls the behaviour of \PDFTEX\ when a~\PDF\ file is included
+that has a~newer version than the one specified by this primitive:
+If it is set to~0, \pdfTeX\ gives only a~warning; if it's~1, \pdfTeX\
+raises an error. The command has been introduced in \PDFTEX\ 1.30.0 as
+a~shortened synonym of \type{\pdfoptionpdfinclusionerrorlevel}, that is
+now obsolete.
+
+\pdftexprimitive {\Syntax {\Tex {\pdfimagehicolor} \Whatever{integer}}}
+
+\bookmark{\type{\pdfimagehicolor}}
+
+This primitive, when set to~1, enables embedding of \PNG\ images with
+16~bit wide color channels at their full color resolution. As such
+an embedding mode is defined only from \PDF\ version~1.5 onwards,
+the \type{\pdfimagehicolor} functionality is automatically disabled
+in \PDFTEX\ if \type{\pdfminorversion}~$<$~5; then each 16~bit
+color channel is reduced to a~width of 8~bit by stripping the lower 8~bits
+before embedding. The same stripping happens when \type{\pdfimagehicolor}
+is set to~0. For \type{\pdfminorversion}~$\ge$~5 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}}}
+
+\bookmark{\type{\pdfimageapplygamma}}
+
+This primitive, when set to~1, enables gamma correction while embedding
+\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}}}
+
+\bookmark{\type{\pdfgamma}}
+
+This primitive defines the `device gamma' for \PDFTEX. Values are in
+promilles (same as for \type{\mag}). The default value of this primitive
+is~1000, defining a~device gamma value of~1.0.
+
+When \type{\pdfimageapplygamma} is set to~1, then whenever a~\PNG\ image
+is included, \PDFTEX\ applies a~gamma correction. This correction is
+based on the  value of the \type{\pdfgamma} primitive and the `assumed
+device gamma' that is derived from the value embedded in the actual
+image. If no embedded value can be found in the \PNG\ image, then the
+value of \type{\pdfimagegamma} is used instead.
+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}}}
+
+\bookmark{\type{\pdfimagegamma}}
+
+This primitive gives a~default `assumed gamma' value for \PNG\ images.
+Values are in promilles (same as for \type{\pdfamma}). The default value
+of this primitive is~2200, implying an assumed gamma value of~2.2.
+
+When \PDFTEX\ is applying gamma corrections, images that do not have an
+embedded `assumed gamma' value are assumed to have been created for
+a~device with a~gamma of 2.2. Experiments show that this default setting
+is correct for a~large number of images; however, if your images come
+out too dark, you probably want to set \type{\pdfimagegamma} to a~lower
+value, like~1000.
+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}}}
+
+\bookmark{\type{\pdfpxdimen}}
+
+While working with bitmap graphics or typesetting electronic documents,
+it might be convenient to base dimensions on pixels rather than \TeX's
+standard units like \type{pt} or \type{em}. For this purpose, \PDFTEX\
+provides an~extra unit called \type{px} that takes the dimension given to
+the \type{\pdfpxdimen} primitive. In example, to make the unit \type{px}
+corresponding to 96\,dpi pixel density (then 1\,px~=~72/96\,bp), one
+can do the following calculation:
+
+\starttyping
+\pdfpxdimen=1in % 1 dpi
+\divide\pdfpxdimen by 96 % 96 dpi
+\hsize=1200px
+\stoptyping
+
+Then \type{\hsize} amounts to 1200~pixels in 96\,dpi, which is
+exactly 903.375\,pt (but \TeX\ rounds it to 903.36914\,pt). The
+default value of \type{\pdfpxdimen} is 1\,bp, corresponding to a~pixel
+density of 72\,dpi. This primitive is completely independent from the
+\type{\pdfimageresolution} and \type{\pdfpkresolution} parameters.
+\introduced{1.30.0} It used to be an integer register that gave
+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.
+
+%***********************************************************************
+
+\subsection{Annotations}
+
+\PDF\ 1.4 provides four basic kinds of annotations:
+
+\startitemize[packed]
+\item hyperlinks, general navigation
+\item text clips (notes)
+\item movies
+\item sound fragments
+\stopitemize
+
+The first type differs from the other three in that there is a~designated
+area involved on which one can click, or when moved over some action occurs.
+\PDFTEX\ is able to calculate this area, as we will see later. All
+annotations can be supported using the next two general annotation
+primitives.
+
+\pdftexprimitive {\Syntax {\Tex {\pdfannot} \Something{annot type spec}}}
+
+\bookmark{\type{\pdfannot}}
+
+This command appends a~whatsit node corresponding to an annotation to the
+list being built. The dimensions of the annotation can be controlled via the
+\Something{rule spec}. The default values are running for all width, height
+and depth. When an annotation is written out, running dimensions will take
+the corresponding values from the box containing the whatsit node
+representing the annotation. The \Something{general 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}}}
+
+\bookmark{\type{\pdflastannot}}
+
+This primitive returns the object number of the last annotation created by
+\type{\pdfannot}. These two primitives allow users to create any annotation
+that cannot be created by \type{\pdfstartlink} (see below).
+
+%***********************************************************************
+
+\subsection[linking]{Destinations and links}
+
+The first type of annotation, mentioned above, is implemented by three
+primitives. The first one is used to define a~specific location as being
+referred to. This location is tied to the page, not the exact location on the
+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}}}
+
+\bookmark{\type{\pdfdest}}
+
+This primitive appends a~whatsit node which establishes a~destination for
+links and bookmark outlines; the link is identified by either a~number or
+a~symbolic name, and the way the viewer is to display the page must be
+specified in \Something{dest type}\unkern, which must be one of those mentioned in
+\in{table}[appearance].
+
+\startbuffer
+\starttabulate[|l|l|]
+\HL
+\NC \bf keyword \NC \bf meaning                                       \NC\NR
+\HL
+\NC \tt fit    \NC fit the page in the window                         \NC\NR
+\NC \tt fith   \NC fit the width of the page                          \NC\NR
+\NC \tt fitv   \NC fit the height of the page                         \NC\NR
+\NC \tt fitb   \NC fit the \quote{Bounding Box} of the page           \NC\NR
+\NC \tt fitbh  \NC fit the width of \quote{Bounding Box} of the page  \NC\NR
+\NC \tt fitbv  \NC fit the height of \quote{Bounding Box} of the page \NC\NR
+\NC \tt xyz    \NC goto the current position (see below)              \NC\NR
+\HL
+\stoptabulate
+\stopbuffer
+
+\placetable
+  [here][appearance]
+  {Options for display of outline and destinations.}
+  {\getbuffer}
+
+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,
+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}}}
+
+\bookmark{\type{\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 \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 \type{\pdfstartlink} and \type{\pdfendlink} will be
+treated as part of the hyperlink. The hyperlink is written out only if the
+corresponding whatsit node is searched at shipout time.
+
+Additional attributes, which are explained in great detail in the
+\PDFReference, can be given via \Something{attr spec}\unkern. Typically,
+the attributes specify the color and thickness of any border around
+the link.  Thus \typ {/C [0.9 0 0] /Border [0 0 2]} specifies a~color
+(in \RGB) of dark red, and a~border thickness of 2~points.
+
+While all graphics and text in a~\PDF\ document have relative positions,
+annotations have internally hard||coded absolute positions. Again this
+is for the sake of speed optimization. The main disadvantage is that these
+annotations do {\em not} obey transformations issued by \type
+{\pdfliteral}'s.
+
+The \Something{action spec} specifies the action that should be performed
+when the hyperlink is activated while the \Something{user-action spec}
+performs a~user||defined action. A~typical use of the latter is to specify
+a~\URL, like \typ {/S /URI /URI (http://www.tug.org/)}, or a~named action like
+\typ {/S /Named /N /NextPage}.
+
+ A~\Something{goto-action spec} performs a~GoTo action. Here \Something
+{numid} and \Something{nameid} specify the destination identifier (see
+below). The \Something{page spec} specifies the page number of the
+destination, in this case the zoom factor is given by \Something{general
+text}\unkern. A~destination can be performed in another \PDF\ file by specifying
+\Something{file spec}\unkern, in which case \Something{newwindow spec} specifies
+whether the file should be opened in a~new window. A~\Something{file spec}
+can be either a~\type{(string)} or a~\type{<<dictionary>>}. The default
+behaviour of the \Something{newwindow spec} depends on the browser setting.
+
+ 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}}}
+
+\bookmark{\type{\pdfendlink}}
+
+This primitive ends a~link started with \type{\pdfstartlink}. All text
+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}}}
+
+\bookmark{\type{\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}}}
+
+\bookmark{\type{\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}}}
+
+\bookmark{\type{\pdfdestmargin}}
+
+Margin added to the dimensions of the rectangle around the destinations.
+
+%***********************************************************************
+
+\subsection{Bookmarks}
+
+\pdftexprimitive {\Syntax {\Tex {\pdfoutline}
+\Optional{\Something{attr spec}} \Something{action spec}
+\Optional{\Literal {count} \Something{integer}} \Something{general text}}}
+
+\bookmark{\type{\pdfoutline}}
+
+This primitive creates an outline (or bookmark) entry. The first parameter
+specifies the action to be taken, and is the same as that allowed for \type
+{\pdfstartlink}. The \Something{count} specifies the number of direct
+subentries under this entry; specify~0 or omit it if this entry has no
+subentries. If the number is negative, then all subentries will be closed and
+the absolute value of this number specifies the number of subentries. The
+\Something{text} is what will be shown in the outline window. Note that this
+is limited to characters in the \PDF\ Document Encoding vector. The outline
+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}}}
+
+\bookmark{\type{\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}}}
+
+\bookmark{\type{\pdfstartthread}}
+
+This uses the same syntax as \type{\pdfthread}, apart that it must be
+followed by a~\type{\pdfendthread}.  \type{\pdfstartthread} and the
+corresponding \type{\pdfendthread} must end up in vboxes with the same
+nesting level; all vboxes between them will be added into the thread.
+Note that during output runtime if there are other newly created
+boxes which have the same nesting level as the vbox/vboxes containing
+\type{\pdfstartthread} and \type{\pdfendthread}, they will be also added
+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}}}
+
+\bookmark{\type{\pdfendthread}}
+
+This ends an article thread started before by \type{\pdfstartthread}.
+
+\pdftexprimitive {\Syntax {\Tex {\pdfthreadmargin} \Whatever{dimension}}}
+
+\bookmark{\type{\pdfthreadmargin}}
+
+Specifies a~margin to be added to the dimensions of a~bead within
+an article thread.
+
+%***********************************************************************
+
+\subsection{Literals and specials}
+
+\pdftexprimitive {\Syntax {\Tex {\pdfliteral} \Optional{\Something {pdfliteral spec}}
+\Something{general text}}}
+
+\bookmark{\type{\pdfliteral}}
+
+Like \type{\special} in normal \TEX, this command inserts raw
+\PDF\ code into the output. This allows support of color and text
+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
+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}.
+
+Starting from version 1.30.0, \PDFTEX\ allows to use a~new keyword
+\type{page} instead of \type{direct}. Both modify the default behaviour
+of \type{\pdfliteral}, avoiding translation of the coordinates space
+before inserting the literal code. The difference is that the \type{page}
+keyword instructs \PDFTEX\ to close a~\type{BT ET} text block before
+inserting anything. It means that the literal code inserted refers to the
+origin (lower||left corner of the page) and can be safely enclosed with
+\type{q Q}. Note, that in most cases using \type{q Q} operators inside
+\type{\pdfliteral} with \type{direct} keyword will produce corrupted
+\PDF\ output, as the \PDF\ standard doesn't allow to do anything like
+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}}
+
+\bookmark{\type{\special}}
+
+This is equivalent to \Syntax{\Tex{\pdfliteral} \Lbrace \Something{text} \Rbrace}.
+
+\pdftexprimitive {\Syntax {\Tex {\special} \Lbrace\unkern\type{pdf:direct:} \Something{text} \Rbrace}}
+
+\bookmark{\type{\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}}
+
+\bookmark{\type{\special\ page}}
+
+This is equivalent to \Syntax{\Tex{\pdfliteral} \Literal{page} \Lbrace \Something{text} \Rbrace}.
+
+%***********************************************************************
+
+\subsection{Strings}
+
+\pdftexprimitive {\Syntax {\Tex {\pdfescapestring} \Something {general text}}}
+
+\bookmark{\type{\pdfescapestring}}
+
+Starting from 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}
+
+\pdftexprimitive {\Syntax {\Tex {\pdfescapename} \Something {general text}}}
+
+\bookmark{\type{\pdfescapename}}
+
+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}
+
+\pdftexprimitive {\Syntax {\Tex {\pdfescapehex} \Something {general text}}}
+
+\bookmark{\type{\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}}}
+
+\bookmark{\type{\pdfunescapehex}}
+
+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}
+
+% Currently it's only experimental, so don't really document it
+\iffalse
+\pdftexprimitive {\Syntax {\Tex {\pdfstrcmp} \Something{general text}
+\Something{general text} \Whatever{expandable}}}
+
+\bookmark{\type{\pdfstrcmp}}
+
+This command compares two strings and expands to 0 if the strings are
+equal, to $-1$ if the first string is $<$ then the second, and to $+1$ if
+the first is $>$ than the second.
+\introduced{1.30.0}
+\fi
+
+\pdftexprimitive{\Syntax {\Tex {\pdfmdfivesum} \Something{general text}
+\Whatever{expandable}}}
+
+\bookmark{\type{\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}} \Something{number}}
+
+\bookmark{\type{\ifpdfabsnum}}
+
+The primitive works as normal \type{\ifnum} condition check, 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 more friendly in usage and works a~bit faster.
+\introduced{1.40.0}
+
+\pdftexprimitive{\Syntax {\Tex {\ifpdfabsdim}} \Something{dimen}}
+
+\bookmark{\type{\ifpdfabsdim}}
+
+Like \type{\ifpdfabsnum}, the primitive works as normal \type{\ifdim} condition check, except
+that it compares absolute values of dimensions. \introduced{1.40.0}
+
+\pdftexprimitive{\Syntax {\Tex {\pdfuniformdeviate} \Something{number} \Whatever{expandable}}}
+
+\bookmark{\type{\pdfuniformdeviate}}
+
+The commands generates 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}}}
+
+\bookmark{\type{\pdfnormaldeviate}}
+
+%MS Hopefully the random number doesn't influce the length of this paragraph;
+%MS otherwise texexec could loop :-)
+The commands generates a~random integer value with a~mean of 0 and a~unit
+of 65\,536, \eg\ $\pdfnormaldeviate$. This primitive expands to a~list of
+tokens. \introduced{1.30.0}
+
+\pdftexprimitive {\Syntax {\Tex {\pdfrandomseed}} \Whatever{read||only
+integer}}
+
+\bookmark{\type{\pdfrandomseed}}
+
+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}
+
+\pdftexprimitive{\Syntax {\Tex {\pdfsetrandomseed} \Something{number}}}
+
+\bookmark{\type{\pdfsetrandomseed}}
+
+This sets the random seed (\type{\pdfrandomseed}) to a~specific value,
+allowing you to re-play sequences of semi-randoms at a~later moment.
+\introduced{1.30.0}
+
+%***********************************************************************
+
+\subsection{Timekeeping}
+
+\pdftexprimitive {\Syntax {\Tex {\pdfelapsedtime}} \Whatever{read||only
+integer}}
+
+\bookmark{\type{\pdfelapsedtime}}
+
+The command expands to a~number that represents the time elapsed from the
+moment of run start. The elapsed time is returned in `scaled seconds', that
+means seconds divided by 65536, \eg\ \PDFTEX\ has run for \the\pdfelapsedtime\
+`scaled seconds' when this paragraph was typeset. Obviously, 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}}
+
+\bookmark{\type{\pdfresettimer}}
+
+The command resets the internal timer so that \type{\pdfelapsedtime}
+starts returning micro||time from~0 again. \introduced{1.30.0}
+
+%***********************************************************************
+
+\subsection{Files}
+
+\pdftexprimitive{\Syntax {\Tex {\pdffilemoddate} \Something{general text}
+\Whatever{expandable}}}
+
+\bookmark{\type{\pdffilemoddate}}
+
+Expands to the modification date of file \Something{general text} in the same
+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}}}
+
+\bookmark{\type{\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}}}
+
+\bookmark{\type{\pdfmdfivesum\ file}}
+
+Expands to the \MDFIVE\ of file \Something{general text} in uppercase
+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{offset
+\Something{number}} \Optional{length \Something{number}} \Something{general
+text} \Whatever{expandable}}}
+
+\bookmark{\type{\pdffiledump}}
+
+Expands to the dump of the file \Something{general text} in uppercase
+hexadecimal format (same as \type{\pdfescapehex}), starting at offset
+\Something{number} or 0 with length \Something{number}, if given. The first ten
+bytes of the source of this manual are {\tt \pdffiledump length 10
+{./pdftex-t.tex}}. \introduced{1.30.0}
+
+%***********************************************************************
+
+\subsection{Colourstack}
+
+\PDFTEX\ 1.40.0 comes with a colour stack support (actually any graphic state
+stack).
+
+\pdftexprimitive{\Syntax {
+\Tex {\pdfcolorstackinit} \Optional{page} \Optional{direct} \Something{general text}
+\Whatever{expandable}}}
+
+\bookmark{\type{\pdfcolorstackinit}}
+
+The primitive initializes new graphic stack and returns its number. Optional
+\Literal{page} keyword instructs \PDFTEX\ to restore the graphic at the
+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}}}
+
+\bookmark{\type{\pdfcolorstack}}
+
+The command operates on the stack of a given number. If \Something{stack action}
+is \Literal{push} keyword, the new value provided as \Something{general text}
+is inserted into the top of the graphic stack and becomes the current stack
+value. If followed by \Literal{pop}, the top value is removed from the stack
+and the new top value becomes the current. \Literal{set} keyword replaces the
+current value with \Something{general text} without changing the stack size.
+\Literal{current} keyword instructs just to use the current stack value
+without modifying the stack at all. \introduced{1.40.0}
+
+\subsection{Transformations}
+
+Since the content of \Tex{\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.
+
+\pdftexprimitive{\Syntax {\Tex {\pdfsetmatrix}}}
+
+\bookmark{\type{\pdfsetmatrix}}
+
+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,
+\Tex{\pdfsetmatrix} primitive expects as an argument a string containing
+just 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}
+
+\pdftexprimitive{\Syntax {\Tex {\pdfsave}}}
+
+\bookmark{\type{\pdfsave}}
+
+The command saves the current transformation by inserting \type{q} operator into the
+content stream. \introduced{1.40.0}
+
+\pdftexprimitive{\Syntax {\Tex {\pdfrestore}}}
+
+\bookmark{\type{\pdfrestore}}
+
+The command restores previously saved transformation by inserting \type{Q}
+operator into the content stream. One should keep in mind that \Tex{\pdfsave}
+and \Tex{\pdfrestore} pairs should always be properly nested and should start
+and end at the same group level. \introduced{1.40.0}
+
+%***********************************************************************
+
+\subsection{Miscellaneous}
+
+\pdftexprimitive {\Syntax {\Tex {\vadjust}
+  \Optional{\Something{pre spec}} \Something{filler}
+  \Lbrace \Something{vertical mode material} \Rbrace }}
+
+\bookmark{\type{\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
+from \Something{vertical mode material} to the current list {\em after}
+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.
+
+\pdftexprimitive {\Syntax {\Tex {\quitvmode}}}
+
+\bookmark{\type{\quitvmode}}
+
+The primitive instructs \PDFTEX\ to quit the vertical mode and start typesetting
+a~paragraph. \type{\quitvmode} has the same effect as \type{\leavevmode} definition
+from \type{plain} macro package. Note however, that \type{\leavevmode} may conflict
+with \type{\everypar} tokens list. No such risk while using \type{\quitvmode} instead.
+\introduced{1.21a}
+
+
+\pdftexprimitive {\Syntax {\Tex {\pdfsavepos}}}
+
+\bookmark{\type{\pdfsavepos}}
+
+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.
+
+\pdftexprimitive {\Syntax {\Tex {\pdflastxpos}} \Whatever{read||only
+integer}}
+
+\bookmark{\type{\pdflastxpos}}
+
+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).
+
+\pdftexprimitive {\Syntax {\Tex {\pdflastypos}} \Whatever{read||only
+integer}}
+
+\bookmark{\type{\pdflastypos}}
+
+This primitive works similar to \type{\pdflastxpos}, only it returns
+the $y$ coordinate.
+
+\pdftexprimitive {\Syntax {\Tex {\pdftexversion} \Whatever{read||only integer}}}
+
+\bookmark{\type{\pdftexversion}}
+\def\versplit#1#2#3{#1.#2#3}
+
+Returns the version of \PDFTEX\ multiplied by 100, \eg\ for \PDFTEX\
+version \expandafter\versplit\the\pdftexversion.\pdftexrevision\ used to
+produce this document, it returns {\tt \number\pdftexversion}.
+
+\pdftexprimitive {\Syntax {\Tex {\pdftexrevision} \Whatever{expandable}}}
+
+\bookmark{\type{\pdftexrevision}}
+
+Returns the revision letter of \PDFTEX, \eg\ for \PDFTEX\ version
+\expandafter\versplit\the\pdftexversion.\pdftexrevision\ used to produce
+this document, it returns the letter {\tt \pdftexrevision}.
+
+\pdftexprimitive {\Syntax {\Tex {\pdftexbanner} \Whatever{expandable}}}
+
+\bookmark{\type{\pdftexbanner}}
+
+Returns the \PDFTEX\ banner message, \eg\ for the version used here:
+{\tt \pdftexbanner}. \introduced{1.20a}
+
+\pdftexprimitive {\Syntax {\Tex {\pdfcreationdate} \Whatever{expandable}}}
+
+\bookmark{\type{\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 {\pdfshellescape} \Whatever{read||only
+integer}}}
+
+\bookmark{\type{\pdfshellescape}}
+
+This primitive is~1 if \type{\write18} is enabled, 0 otherwise.
+\type{\write18} was \ifnum\pdfshellescape=0\relax not \fi enabled when this
+manual was typeset.
+\introduced{1.30.0}
+
+\pdftexprimitive {\Syntax {\tex {ifpdfprimitive} \Something{control sequence} \Whatever{expandable}}}
+
+\bookmark{\tex{ifpdfprimitive}}
+
+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}
+
+
+\pdftexprimitive {\Syntax {\tex {pdfprimitive} \Something{control sequence}}}
+
+\bookmark{\type{\pdfprimitive}}
+
+This command executes the primitive meaning of the following control sequence,
+if it has been redefined or made undefined. If the following control sequence is
+undefined and never was a~primitive, nothing happens and no error is raised.
+If the control sequence was initially expandable, \type{\pdfprimitive}
+expands either. Otherwise \type{\pdfprimitive} doesn't expand. \introduced{1.40.0}
+
+\pdftexprimitive {\Syntax {\tex {pdfdraftmode} \Whatever{integer}}}
+
+\bookmark{\type{\pdfdraftmode}}
+
+%FIXME: -draftmode should be in tt; bibtex-logo is wrong
+When set to 1 (or switched on by the commandline switch -draftmode) \PDFTEX\
+doesn't write the output pdf and doesn't actually read any images but does
+everything else (including writing auxiliary files), thus speeding up
+compilations when you know you need an extra run but don't care about the
+output, e.g. just to get the \BIBTEX\ references right.
+\introduced{1.40.0}
+
+%***********************************************************************
+
+\section{Graphics and color}
+
+\PDFTEX\ supports inclusion of pictures in \PNG, \JPEG, \JBIGTWO, and
+\PDF\ format; a~few differences between these are discussed below. The
+most common technique with \TEX\ |<|the inclusion of \EPS\ figures|>|
+is replaced by \PDF\ inclusion. \EPS\ files can be converted to \PDF\ by
+\GHOSTSCRIPT, Adobe Distiller or other \POSTSCRIPT||to||\PDF\ converters.
+
+The \PDF\ format is currently the most versatile source format for
+graphics embedding. \PDFTEX\ allows to insert arbitrary pages from
+\PDF\ files with their own fonts, graphics, and pixel images into
+a~document. The cover page of this manual is an example of such an insert,
+being a~one page document generated by \PDFTEX.
+
+By default \PDFTEX\ takes the BoundingBox of a~\PDF\ file from its CropBox
+if available, otherwise from its MediaBox. This can be influenced by
+the \Something{pdf box spec} option to the \type{\pdfximage} primitive,
+or by setting the \type{\pdfforcepagebox} primitive to
+a~value corresponding to the wanted box type.
+
+To get the right BoundingBox from a~\EPS\ file, before converting to \PDF,
+it is necessary to transform the \EPS\ file so that the start point is
+at the (0,0)~coordinate and the page size is set exactly corresponding
+to the BoundingBox. A~\PERL\ script (\EPSTOPDF) for this purpose has been
+written. The \TEXUTIL\ utility script and the \PSTOPDF\ program that comes
+with \GHOSTSCRIPT\ can so a~similar job. (Concerning this conversion,
+they can handle complete directories, remove some garbage from files,
+takes precautions against duplicate conversion, etc.)
+
+The lossless compressing \PNG\ format is great for embedding crisp pixel
+graphics (\eg\ line scans, screen shots). Since \PDFTEX\ 1.30.0 also the
+alpha-channel of \PNG\ images is processed if available; this allows
+embedding of images with simple transparency. The \PNG\ format does not
+support the CMYK color model, which is sometimes required for print media
+(this often can be replaced by four component \JPEG\ in high quality or
+lossless compression mode). Photos in \PNG\ format have a~rather weak
+compression; here the \JPEG\ format is preferable.
+
+Embedding \PNG\ images in the general case requires \PDFTEX\ to uncompress
+the pixel array and to re||compress it to the \PDF\ requirements; this
+process often takes a~noticeable amount of time. Since \PDFTEX\ 1.30.0
+there is now a~fast \PNG\ embedding mode that goes without uncompressing;
+the image data are directly copied into the \PDF\ stream, resulting in
+a~much higher embedding speed. However this mode is only activated, if
+the image array structure of the \PNG\ file is compatible with the \PDF\
+image structure (\eg\ an interlaced \PNG\ image requires uncompressing to
+re||arrange the image lines). Luckily it seems that the most common \PNG\
+files also allow fast copying. The use of gamma correction disables fast
+copying, as it requires calculations with individual pixels. Whether the
+fast copy mode is used for a~\PNG\ image can be seen from the log file,
+which then shows the string `(PNG copy)' after the \PNG\ file name.
+
+The \JPEG\ format is normally used in lossy mode; then it's ideal for
+embedding photos; it's not recommended for crisp images from synthetic
+sources with a~limited amount of colors.
+
+The \JBIGTWO\ format works only for bitonal (black and white) pixel
+images like scanned line and text documents, but for these it has
+typically a~much higher compression ratio than the other two pixel
+image formats. The \JBIGTWO\ format is part of the \PDF\ standard since
+version 1.5; native \JBIGTWO\ image inclusion is available in \PDFTEX\
+since version 1.40.0. A~\JBIGTWO\ file might contain many images, which
+gives an even better compression ratio than with a~single image per file,
+as \JBIGTWO\ encoders can exploit similarities between bit patterns over
+several images. Encoders for \JBIGTWO\ can operate in lossy as well as
+lossless modes. Only recently a~free \JBIGTWO\ encoder has been written
+and made available, see http:/\!/www.imperialviolet.org/jbig2.html.
+
+Other options for graphics in \PDFTEX\ are:
+
+\description {\LATEX\ picture mode} Since this is implemented simply in terms
+of font characters, it works in exactly the same way as usual.
+
+\description {Xy||pic} If the \POSTSCRIPT\ back||end is not requested, Xy||pic
+uses its own Type~1 fonts, and needs no special attention.
+
+\description {tpic} The \quote {tpic} \type{\special} commands (used in some
+macro packages) can be redefined to produce literal \PDF, using some macros
+written by Hans Hagen.
+
+\description {\METAPOST} Although the output of \METAPOST\ is \POSTSCRIPT,
+it is in a~highly simplified form, and a~\METAPOST\ to \PDF\ conversion
+(\MPTOPDF, written by Hans Hagen and Tanmoy Bhattacharya) is implemented
+as a~set of macros which reads \METAPOST\ output and supports all of
+its features.
+
+For new work, the \METAPOST\ route is highly recommended. For the future,
+Adobe has announced that they will define a~specification for \quote
+{encapsulated \PDF}.
+
+The inclusion of raw \POSTSCRIPT\ commands |<|a technique utilized
+by for instance the \type{pstricks} package|>| cannot directly be
+supported. Although \PDF\ is direct a~descendant of \POSTSCRIPT, it
+lacks any programming language commands, and cannot deal with arbitrary
+\POSTSCRIPT.
+
+%***********************************************************************
+
+\section{Character translation}
+
+Characters that are input to \PDFTEX\ are subject to optional
+\TEX\ character translation (\TCX) under control of a~\TCX\ file.
+The \TCX\ maps the input character codes (\eg\ from \type{\input} or
+\type{\read}) to the character codes as seen by \PDFTEX.  This mapping
+takes place before the characters enter \PDFTEX's `mouth'.  If no \TCX\
+file is read, the input characters enter \PDFTEX\ directly; no mapping
+is done.
+
+\TCX\ files consist of lines each containing one or two integer numbers
+in the range 0..255, either in decimal or hex notation.
+% strtol() C-function
+ A~comment sign \type{%} in a~\TCX\ line starts a~comment until the
+end of line.  The first number in each line is for matching the input
+character code, the second, optional number is the corresponding \TEX\
+character code.  If a~line contains only one number, characters with
+this code enter \PDFTEX\ unchanged; no mapping is done.
+
+\TCX\ mapping also influences \PDFTEX\ output streams for \type{\message} and
+\type{\write}.  Without \TCX\ mapping, only characters that are within
+the range 32..126 are flagged as `printable', meaning that these
+characters are output directly by \type{\message} and \type{\write}
+primitives.  Characters outside the range 32..126 are instead output
+in escaped form, \eg\ as \type{^^A} for a~character with code
+\type{0x01}.  When a~character code is mentioned in the 2nd column of the
+\TCX\ file, or as the only value in a~line, it is flagged as `printable'.
+During \type{\message} and \type{\write}, output characters are mapped
+in reverse direction: they are looked up in the 2nd column of the \TCX\
+file and the corresponding values from the 1st column are output.  Again,
+if a~\PDFTEX\ character code is found as the only number in a~line, no
+mapping is done.  Mentioning a~character code as the only number on
+a~line has the sole purpose to flag this code `printable'; remember that
+character within the range 32..126 are `printable' anyway.
+
+The characters output into the \PDF\ file, \eg\ by \type{\pdfliteral}
+or \type{\special} primitives, are not subject to \TCX\ output remapping.
+
+Beware: Character translation interferes with the \ENCTEX\ primitives; to
+avoid surprises, don't use \ENCTEX\ and \TCX\ mapping at the same time.
+Further details about \TCX\ file loading can be found in the \TETEX\
+manual.
+
+%***********************************************************************
+
+\stopbodymatter
+
+%D We did use some abbreviations. Only those really used will end up in the
+%D following list.
+
+\startbackmatter
+
+\writebetweenlist[section]{\blank[line]}
+
+%***********************************************************************
+
+\section{Abbreviations}
+
+In this document we used a~few abbreviations. For convenience we mention
+their meaning here.
+
+\placelistofabbreviations
+
+%***********************************************************************
+
+\start \setupalign[nothanging,nohz]
+
+\section{Examples of HZ and protruding}
+
+In the following sections we will demonstrate \PDFTEX's protruding and
+\HZ\ features, using a~text from E.~Tufte. This sample text has a~lot
+of punctuation and often needs hyphenation. Former \PDFTEX\ versions
+had sometimes problems with combining these features, but from version
+1.21a on it should be ok. If you still encounter problems, please try
+to prepare a~small test file that demonstrates the problem and send it
+to one of the maintainers.
+
+\startbuffer
+    \input tufte
+    \blank[big]
+    \startcolumns
+        \input tufte
+    \stopcolumns
+\stopbuffer
+
+\subsection{Normal}     \start                         \getbuffer \stop
+\subsection{HZ}         \start \setupalign[hz]         \getbuffer \stop
+\subsection{Protruding} \start \setupalign[hanging]    \getbuffer \stop
+\subsection{Both}       \start \setupalign[hz,hanging] \getbuffer \stop
+
+\stop
+
+%***********************************************************************
+
+\section{Additional \PDF\ keys}
+
+{\em This section is based on the manual on keys written by Martin
+Schr\"oder, one of the maintainers of \PDFTEX.}
+
+ A~\PDF\ document should contain only the structures and attributes defined
+in the \PDF\ specification. However, the specification allows applications
+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.
+
+\PDFTEX\ generates an XObject for every included \PDF. The dictionary of
+this object contains these additional keys:
+
+\starttabulate[|lT|l|p|]
+\HL
+\NC \bf key         \NC \bf type   \NC meaning \NC \NR
+\HL
+\NC PTEX.FileName   \NC string     \NC The name of the included file as seen by
+                                       \PDFTEX. \NC \NR
+\NC PTEX.InfoDict   \NC dictionary \NC The document information dictionary of the included
+                                       \PDF\ (an indirect object). \NC \NR
+\NC PTEX.PageNumber \NC integer    \NC The page number of the included file. \NC \NR
+\HL
+\stoptabulate
+
+The \PDFReference\ says: \quotation {Although viewer applications can
+store custom metadata in the document information dictionary, it is
+inappropriate to store private content or structural information there;
+such information should be stored in the document catalog instead.}
+
+Although it would seem more natural to put this infomation in the
+document information dictionary, we have to obey the rules laid down in
+the \PDFReference. The following key ends up in the document catalog.
+
+\starttabulate[|lT|l|p|]
+\HL
+\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\
+{\tt\pdftexbanner}.  This is necessary because the string in the
+\type {Producer} key in the info dictionary is rather short,
+\eg\ {\tt pdfTeX-\currentpdftex}. \NC \NR
+\HL
+\stoptabulate
+
+%***********************************************************************
+
+\section{Colophon}
+
+This manual is typeset in \CONTEXT. One can generate an A4 version from
+the source code by typing:
+
+\starttyping
+texexec --result=pdftex-a.pdf pdftex-t
+\stoptyping
+
+Or in letter size:
+
+\starttyping
+texexec  --mode=letter --result=pdftex-l.pdf pdftex-t
+\stoptyping
+
+Given that the A4 version is typeset, one can generate an A5 booklet by
+typing:
+
+\starttyping
+texexec --pdfarrange --paper=a5a4 --print=up --addempty=1,2
+  --result=pdftex-b.pdf pdftex-a
+\stoptyping
+
+Odd and even page sets for non-duplex printers can be generated using
+\type{--pages=odd} and \type{--pages=even} options
+(which might require some disciplined shuffling of sheet).
+
+This also demonstrates that \PDFTEX\ can be used for page imposition
+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]
+
+\setuphead[gnusection,gnusubject][style=\bfa,before=\blank,after=\blank,align={right,broad,nothyphenated}]
+
+\setuphead[gnusection][ownnumber=yes]
+
+\section{GNU Free Documentation License}
+
+\startnotmode[screen]
+    \switchtobodyfont[4.35pt] % squeeze everything on one page :-}
+    \setuplayout[grid=yes]
+    \setupcolumns[n=7]
+\stopnotmode
+
+\startmode[screen]
+    \setupcolumns[n=2]
+\stopmode
+
+\startcolumns[tolerance=verytolerant,distance=10pt] \widowpenalty10000 \clubpenalty10000
+
+\startlines
+Version 1.2, November 2002
+Copyright \copyright\ 2000, 2001, 2002
+Free Software Foundation, Inc.
+59 Temple Place, Suite 330,
+Boston, MA  02111-1307  USA
+\stoplines
+
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+
+\gnusubject{Preamble}
+
+The purpose of this License is to make a~manual, textbook, or other
+functional and useful document ``free'' in the sense of freedom: to
+assure everyone the effective freedom to copy and redistribute it,
+with or without modifying it, either commercially or noncommercially.
+Secondarily, this License preserves for the author and publisher a~way
+to get credit for their work, while not being considered responsible
+for modifications made by others.
+
+This License is a~kind of ``copyleft'', which means that derivative
+works of the document must themselves be free in the same sense.  It
+complements the GNU General Public License, which is a~copyleft
+license designed for free software.
+
+We have designed this License in order to use it for manuals for free
+software, because free software needs free documentation: a~free
+program should come with manuals providing the same freedoms that the
+software does.  But this License is not limited to software manuals;
+it can be used for any textual work, regardless of subject matter or
+whether it is published as a~printed book.  We recommend this License
+principally for works whose purpose is instruction or reference.
+
+\gnusection{1}{APPLICABILITY AND DEFINITIONS}
+
+This License applies to any manual or other work, in any medium, that
+contains a~notice placed by the copyright holder saying it can be
+distributed under the terms of this License.  Such a~notice grants
+a~world-wide, royalty-free license, unlimited in duration, to use that
+work under the conditions stated herein.  The {\bf ``Document''}, below,
+refers to any such manual or work.  Any member of the public is
+a~licensee, and is addressed as {\bf ``you''}.  You accept the license if you
+copy, modify or distribute the work in a~way requiring permission
+under copyright law.
+
+ A~{\bf ``Modified Version''} of the Document means any work containing the
+Document or a~portion of it, either copied verbatim, or with
+modifications and/or translated into another language.
+
+ A~{\bf ``Secondary Section''} is a~named appendix or a~front-matter section of
+the Document that deals exclusively with the relationship of the
+publishers or authors of the Document to the Document's overall subject
+(or to related matters) and contains nothing that could fall directly
+within that overall subject.  (Thus, if the Document is in part
+a~textbook of mathematics, a~Secondary Section may not explain any
+mathematics.)  The relationship could be a~matter of historical
+connection with the subject or with related matters, or of legal,
+commercial, philosophical, ethical or political position regarding
+them.
+
+The {\bf ``Invariant Sections''} are certain Secondary Sections whose titles
+are designated, as being those of Invariant Sections, in the notice
+that says that the Document is released under this License.  If
+a~section does not fit the above definition of Secondary then it is not
+allowed to be designated as Invariant.  The Document may contain zero
+Invariant Sections.  If the Document does not identify any Invariant
+Sections then there are none.
+
+The {\bf ``Cover Texts''} are certain short passages of text that are listed,
+as Front-Cover Texts or Back-Cover Texts, in the notice that says that
+the Document is released under this License. A~Front-Cover Text may
+be at most 5 words, and a~Back-Cover Text may be at most 25 words.
+
+ A~{\bf ``Transparent''} copy of the Document means a~machine-readable copy,
+represented in a~format whose specification is available to the
+general public, that is suitable for revising the document
+straightforwardly with generic text editors or (for images composed of
+pixels) generic paint programs or (for drawings) some widely available
+drawing editor, and that is suitable for input to text formatters or
+for automatic translation to a~variety of formats suitable for input
+to text formatters. A~copy made in an otherwise Transparent file
+format whose markup, or absence of markup, has been arranged to thwart
+or discourage subsequent modification by \PDF\ viewers is not Transparent.
+An image format is not Transparent if used for any substantial amount
+of text. A~copy that is not ``Transparent'' is called {\bf ``Opaque''}.
+
+Examples of suitable formats for Transparent copies include plain
+ASCII without markup, Texinfo input format, LaTeX input format, SGML
+or XML using a~publicly available DTD, and standard-conforming simple
+HTML, \POSTSCRIPT\ or \PDF\ designed for human modification.  Examples of
+transparent image formats include PNG, XCF and JPG.  Opaque formats
+include proprietary formats that can be read and edited only by
+proprietary word processors, SGML or XML for which the DTD and/or
+processing tools are not generally available, and the
+machine-generated HTML, \POSTSCRIPT\ or \PDF\ produced by some word
+processors for output purposes only.
+
+The {\bf ''Title Page''} means, for a~printed book, the title page itself,
+plus such following pages as are needed to hold, legibly, the material
+this License requires to appear in the title page.  For works in
+formats which do not have any title page as such, ``Title Page'' means
+the text near the most prominent appearance of the work's title,
+preceding the beginning of the body of the text.
+
+ A~section {\bf ``Entitled XYZ''} means a~named subunit of the Document whose
+title either is precisely XYZ or contains XYZ in parentheses following
+text that translates XYZ in another language.  (Here XYZ stands for
+a~specific section name mentioned below, such as {\bf ``Acknowledgements''},
+{\bf ``Dedications''}, {\bf ``Endorsements''}, or {\bf ``History''}.)
+To {\bf ``Preserve the Title''}
+of such a~section when you modify the Document means that it remains
+a~section ``Entitled XYZ'' according to this definition.
+
+The Document may include Warranty Disclaimers next to the notice which
+states that this License applies to the Document.  These Warranty
+Disclaimers are considered to be included by reference in this
+License, but only as regards disclaiming warranties: any other
+implication that these Warranty Disclaimers may have is void and has
+no effect on the meaning of this License.
+
+
+\gnusection{2}{VERBATIM COPYING}
+
+You may copy and distribute the Document in any medium, either
+commercially or noncommercially, provided that this License, the
+copyright notices, and the license notice saying this License applies
+to the Document are reproduced in all copies, and that you add no other
+conditions whatsoever to those of this License.  You may not use
+technical measures to obstruct or control the reading or further
+copying of the copies you make or distribute.  However, you may accept
+compensation in exchange for copies.  If you distribute a~large enough
+number of copies you must also follow the conditions in section 3.
+
+You may also lend copies, under the same conditions stated above, and
+you may publicly display copies.
+
+
+\gnusection{3}{COPYING IN QUANTITY}
+
+If you publish printed copies (or copies in media that commonly have
+printed covers) of the Document, numbering more than 100, and the
+Document's license notice requires Cover Texts, you must enclose the
+copies in covers that carry, clearly and legibly, all these Cover
+Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
+the back cover.  Both covers must also clearly and legibly identify
+you as the publisher of these copies.  The front cover must present
+the full title with all words of the title equally prominent and
+visible.  You may add other material on the covers in addition.
+Copying with changes limited to the covers, as long as they preserve
+the title of the Document and satisfy these conditions, can be treated
+as verbatim copying in other respects.
+
+If the required texts for either cover are too voluminous to fit
+legibly, you should put the first ones listed (as many as fit
+reasonably) on the actual cover, and continue the rest onto adjacent
+pages.
+
+If you publish or distribute Opaque copies of the Document numbering
+more than 100, you must either include a~machine-readable Transparent
+copy along with each Opaque copy, or state in or with each Opaque copy
+a~computer-network location from which the general network-using
+public has access to download using public-standard network protocols
+a~complete Transparent copy of the Document, free of added material.
+If you use the latter option, you must take reasonably prudent steps,
+when you begin distribution of Opaque copies in quantity, to ensure
+that this Transparent copy will remain thus accessible at the stated
+location until at least one year after the last time you distribute an
+Opaque copy (directly or through your agents or retailers) of that
+edition to the public.
+
+It is requested, but not required, that you contact the authors of the
+Document well before redistributing any large number of copies, to give
+them a~chance to provide you with an updated version of the Document.
+
+
+\gnusection{4}{MODIFICATIONS}
+
+You may copy and distribute a~Modified Version of the Document under
+the conditions of sections 2 and 3 above, provided that you release
+the Modified Version under precisely this License, with the Modified
+Version filling the role of the Document, thus licensing distribution
+and modification of the Modified Version to whoever possesses a~copy
+of it.  In addition, you must do these things in the Modified Version:
+
+\startitemize[A,packed]
+\item
+   Use in the Title Page (and on the covers, if any) a~title distinct
+   from that of the Document, and from those of previous versions
+   (which should, if there were any, be listed in the History section
+   of the Document).  You may use the same title as a~previous version
+   if the original publisher of that version gives permission.
+
+\item
+   List on the Title Page, as authors, one or more persons or entities
+   responsible for authorship of the modifications in the Modified
+   Version, together with at least five of the principal authors of the
+   Document (all of its principal authors, if it has fewer than five),
+   unless they release you from this requirement.
+
+\item
+   State on the Title page the name of the publisher of the
+   Modified Version, as the publisher.
+
+\item
+   Preserve all the copyright notices of the Document.
+
+\item
+   Add an appropriate copyright notice for your modifications
+   adjacent to the other copyright notices.
+
+\item
+   Include, immediately after the copyright notices, a~license notice
+   giving the public permission to use the Modified Version under the
+   terms of this License, in the form shown in the Addendum below.
+
+\item
+   Preserve in that license notice the full lists of Invariant Sections
+   and required Cover Texts given in the Document's license notice.
+
+\item
+   Include an unaltered copy of this License.
+
+\item
+   Preserve the section Entitled ``History'', Preserve its Title, and add
+   to it an item stating at least the title, year, new authors, and
+   publisher of the Modified Version as given on the Title Page.  If
+   there is no section Entitled ``History'' in the Document, create one
+   stating the title, year, authors, and publisher of the Document as
+   given on its Title Page, then add an item describing the Modified
+   Version as stated in the previous sentence.
+
+\item
+   Preserve the network location, if any, given in the Document for
+   public access to a~Transparent copy of the Document, and likewise
+   the network locations given in the Document for previous versions
+   it was based on.  These may be placed in the ``History'' section.
+   You may omit a~network location for a~work that was published at
+   least four years before the Document itself, or if the original
+   publisher of the version it refers to gives permission.
+
+\item
+   For any section Entitled ``Acknowledgements'' or ``Dedications'',
+   Preserve the Title of the section, and preserve in the section all
+   the substance and tone of each of the contributor acknowledgements
+   and/or dedications given therein.
+
+\item
+   Preserve all the Invariant Sections of the Document,
+   unaltered in their text and in their titles.  Section numbers
+   or the equivalent are not considered part of the section titles.
+
+\item
+   Delete any section Entitled ``Endorsements''.  Such a~section
+   may not be included in the Modified Version.
+
+\item
+   Do not retitle any existing section to be Entitled ``Endorsements''
+   or to conflict in title with any Invariant Section.
+
+\item
+   Preserve any Warranty Disclaimers.
+\stopitemize
+
+If the Modified Version includes new front-matter sections or
+appendices that qualify as Secondary Sections and contain no material
+copied from the Document, you may at your option designate some or all
+of these sections as invariant.  To do this, add their titles to the
+list of Invariant Sections in the Modified Version's license notice.
+These titles must be distinct from any other section titles.
+
+You may add a~section Entitled ``Endorsements'', provided it contains
+nothing but endorsements of your Modified Version by various
+parties--for example, statements of peer review or that the text has
+been approved by an organization as the authoritative definition of
+a~standard.
+
+You may add a~passage of up to five words as a~Front-Cover Text, and
+a~passage of up to 25 words as a~Back-Cover Text, to the end of the list
+of Cover Texts in the Modified Version.  Only one passage of
+Front-Cover Text and one of Back-Cover Text may be added by (or
+through arrangements made by) any one entity.  If the Document already
+includes a~cover text for the same cover, previously added by you or
+by arrangement made by the same entity you are acting on behalf of,
+you may not add another; but you may replace the old one, on explicit
+permission from the previous publisher that added the old one.
+
+The author(s) and publisher(s) of the Document do not by this License
+give permission to use their names for publicity for or to assert or
+imply endorsement of any Modified Version.
+
+\gnusection{5}{COMBINING DOCUMENTS}
+
+You may combine the Document with other documents released under this
+License, under the terms defined in section 4 above for modified
+versions, provided that you include in the combination all of the
+Invariant Sections of all of the original documents, unmodified, and
+list them all as Invariant Sections of your combined work in its
+license notice, and that you preserve all their Warranty Disclaimers.
+
+The combined work need only contain one copy of this License, and
+multiple identical Invariant Sections may be replaced with a~single
+copy.  If there are multiple Invariant Sections with the same name but
+different contents, make the title of each such section unique by
+adding at the end of it, in parentheses, the name of the original
+author or publisher of that section if known, or else a~unique number.
+Make the same adjustment to the section titles in the list of
+Invariant Sections in the license notice of the combined work.
+
+In the combination, you must combine any sections Entitled ``History''
+in the various original documents, forming one section Entitled
+``History''; likewise combine any sections Entitled ``Acknowledgements'',
+and any sections Entitled ``Dedications''.  You must delete all sections
+Entitled ``Endorsements''.
+
+\gnusection{6}{COLLECTIONS OF DOCUMENTS}
+
+You may make a~collection consisting of the Document and other documents
+released under this License, and replace the individual copies of this
+License in the various documents with a~single copy that is included in
+the collection, provided that you follow the rules of this License for
+verbatim copying of each of the documents in all other respects.
+
+You may extract a~single document from such a~collection, and distribute
+it individually under this License, provided you insert a~copy of this
+License into the extracted document, and follow this License in all
+other respects regarding verbatim copying of that document.
+
+\gnusection{7}{AGGREGATION WITH INDEPENDENT WORKS}
+
+ A~compilation of the Document or its derivatives with other separate
+and independent documents or works, in or on a~volume of a~storage or
+distribution medium, is called an ``aggregate'' if the copyright
+resulting from the compilation is not used to limit the legal rights
+of the compilation's users beyond what the individual works permit.
+When the Document is included in an aggregate, this License does not
+apply to the other works in the aggregate which are not themselves
+derivative works of the Document.
+
+If the Cover Text requirement of section 3 is applicable to these
+copies of the Document, then if the Document is less than one half of
+the entire aggregate, the Document's Cover Texts may be placed on
+covers that bracket the Document within the aggregate, or the
+electronic equivalent of covers if the Document is in electronic form.
+Otherwise they must appear on printed covers that bracket the whole
+aggregate.
+
+\gnusection{8}{TRANSLATION}
+
+Translation is considered a~kind of modification, so you may
+distribute translations of the Document under the terms of section 4.
+Replacing Invariant Sections with translations requires special
+permission from their copyright holders, but you may include
+translations of some or all Invariant Sections in addition to the
+original versions of these Invariant Sections.  You may include
+a~translation of this License, and all the license notices in the
+Document, and any Warranty Disclaimers, provided that you also include
+the original English version of this License and the original versions
+of those notices and disclaimers.  In case of a~disagreement between
+the translation and the original version of this License or a~notice
+or disclaimer, the original version will prevail.
+
+If a~section in the Document is Entitled ``Acknowledgements'',
+``Dedications'', or ``History'', the requirement (section 4) to Preserve
+its Title (section~1) will typically require changing the actual
+title.
+
+\gnusection{9}{TERMINATION}
+
+You may not copy, modify, sublicense, or distribute the Document except
+as expressly provided for under this License.  Any other attempt to
+copy, modify, sublicense or distribute the Document is void, and will
+automatically terminate your rights under this License.  However,
+parties who have received copies, or rights, from you under this
+License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
+\gnusection{10}{FUTURE REVISIONS OF THIS LICENSE}
+
+The Free Software Foundation may publish new, revised versions
+of the GNU Free Documentation License from time to time.  Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.  See
+http:/\!/www.gnu.org/copyleft/.
+
+Each version of the License is given a~distinguishing version number.
+If the Document specifies that a~particular numbered version of this
+License ``or any later version'' applies to it, you have the option of
+following the terms and conditions either of that specified version or
+of any later version that has been published (not as a~draft) by the
+Free Software Foundation.  If the Document does not specify a~version
+number of this License, you may choose any version ever published (not
+as a~draft) by the Free Software Foundation.
+\stopcolumns
+
+%***********************************************************************
+
+\stopbackmatter
+
+%D And then we're done.
+
+\stoptext
-- 
cgit v1.2.3

