summaryrefslogtreecommitdiff
path: root/Master/texmf/doc/pdftex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf/doc/pdftex')
-rw-r--r--Master/texmf/doc/pdftex/NEWS400
-rw-r--r--Master/texmf/doc/pdftex/README90
-rw-r--r--Master/texmf/doc/pdftex/manual/makefiles.cmd13
-rw-r--r--Master/texmf/doc/pdftex/manual/pdftex-t.tex4833
-rw-r--r--Master/texmf/doc/pdftex/manual/pdftex-w.pdf66
-rw-r--r--Master/texmf/doc/pdftex/manual/samplepdf/pdfcolor.tex158
-rw-r--r--Master/texmf/doc/pdftex/manual/samplepdf/pic.pdfbin0 -> 36792 bytes
-rw-r--r--Master/texmf/doc/pdftex/manual/samplepdf/rgb.iccbin0 -> 744 bytes
-rw-r--r--Master/texmf/doc/pdftex/manual/samplepdf/samplepdf.024
-rw-r--r--Master/texmf/doc/pdftex/manual/samplepdf/samplepdf.tex1161
-rw-r--r--Master/texmf/doc/pdftex/manual/samplepdf/supp-mis.tex695
-rw-r--r--Master/texmf/doc/pdftex/manual/samplepdf/supp-pdf.tex2191
-rw-r--r--Master/texmf/doc/pdftex/manual/samplepdf/tmp.pdfbin0 -> 3031 bytes
-rw-r--r--Master/texmf/doc/pdftex/pdftex-pdfkeys/Makefile29
-rw-r--r--Master/texmf/doc/pdftex/pdftex-pdfkeys/fdl.tex368
-rw-r--r--Master/texmf/doc/pdftex/pdftex-pdfkeys/pdftex-pdfkeys.bbl16
-rw-r--r--Master/texmf/doc/pdftex/pdftex-pdfkeys/pdftex-pdfkeys.pdfbin0 -> 132564 bytes
-rw-r--r--Master/texmf/doc/pdftex/pdftex-pdfkeys/pdftex-pdfkeys.tex210
18 files changed, 10254 insertions, 0 deletions
diff --git a/Master/texmf/doc/pdftex/NEWS b/Master/texmf/doc/pdftex/NEWS
new file mode 100644
index 00000000000..643b9119b2b
--- /dev/null
+++ b/Master/texmf/doc/pdftex/NEWS
@@ -0,0 +1,400 @@
+-------------------------------------------------
+pdfTeX 3.141592-1.30.4 was released on 2005-10-17
+-------------------------------------------------
+- bugfix: whitespaces in filenames didn't work on Unix anymore (bug 377)
+- bugfix: two \immediates cancel themselves (bug 437)
+- bugfix: wrong file name in error messages of image inclusion (bug 435)
+
+-------------------------------------------------
+pdfTeX 3.141592-1.30.3 was released on 2005-09-04
+-------------------------------------------------
+- bugfix: \write18
+
+-------------------------------------------------
+pdfTeX 3.141592-1.30.2 was released on 2005-08-25
+-------------------------------------------------
+- fixed some build problems and minor bugs introduced in 1.30.1
+
+-------------------------------------------------
+pdfTeX 3.141592-1.30.1 was released on 2005-08-21
+-------------------------------------------------
+- the eTeX extensions can now be enabled with the cmdline switch -etex
+- pdfTeX uses xpdf 3.01
+
+-------------------------------------------------
+pdfTeX 3.141592-1.30.0 was released on 2005-08-01
+-------------------------------------------------
+- pdfxtex (introduced with 1.20a) is gone; all extensions are now in pdf(e)tex.
+- Some primitives have been renamed; the old names will still work, but are
+ deprecated and some give a warning that they are obsolete:
+ \pdfoptionpdfminorversion -> \pdfminorversion
+ \pdfoptionalwaysusepdfpagebox -> \pdfforcepagebox
+ \pdfoptionpdfinclusionerrorlevel -> \pdfinclusionerrorlevel
+- pdftex knows two new units:
+ - new Didot (1nd=0.375mm)
+ - new Cicero (1nc=12nd)
+- New primitives:
+ - Inclusion of pngs has been greatly improved: It now does
+ - alpha channel and transparency (only if %!PDF >=1.4)
+ - 16-bit colour (only if %!PDF >=1.5); this must be enabled by setting
+ \pdfimagehicolor to 1.
+ - gamma correction; this must be enabled by setting \pdfimageapplygamma to
+ 1. The device gamma is taken from \pdfgamma. If no embedded value can be
+ found in the png image, then the value of \pdfimagegamma is used instead.
+ - fast direct embedding of png streams, if their structure allows this; the
+ automatic fall-back is to decompress and re-compress as before.
+ - pdfTeX now has an interface to the precise system time (if available) as an
+ aid in benchmarking TeX macro code.
+ - \pdfelapsedtime is a read-only integer that (initially) returns the
+ amount of time passed since the start of this run. This amount is given
+ in `scaled seconds': the value 65536 counts as one second. If more time
+ has passed than 32767 seconds, (2^31)-1 will be returned.
+ - \pdfresettimer updates the internal timer, such that subsequent calls to
+ \pdfelapsedtime will restart from 0.
+ - pdfTeX can now generate random numbers:
+ - \pdfuniformdeviate <count> generates a uniformly distributed random
+ integer value between 0 (inclusive) and <count> (exclusive).
+ - \pdfnormaldeviate expands to a random integer value with a mean of 0 and
+ a unit of 65536.
+ - \pdfrandomseed allows access to the current seed value.
+ - \pdfsetrandomseed <count> sets the random seed to a specific value.
+ - \pdfnoligatures\f disables ligatures for the loaded font \f.
+ - Escaping strings:
+ - \pdfescapestring{<a>} escapes the string <a> so that it can be used as
+ PDF string.
+ - \pdfescapename{<a>} escapes the string <a> so that it can be used as PDF
+ name.
+ - \pdfescapehex{<a>} converts the string <a> to uppercase hexadecimal
+ representation.
+ - \pdfunescapehex{<b>} reverses the effect of \pdfescapehex
+ - \pdfcreationdate expands to the date string that pdfTeX uses in the info
+ dict as default.
+ - \pdffilemoddate{<file>} expands to the modification date of <file> in the
+ same format as \pdfcreationdate (PDF date format).
+ - \pdffilesize{<file>} expands to the size of <file> as string.
+ - \pdfmdfivesum{<abc>} or \pdfmdfivesum file {<file>} calculates the md5
+ sum (of a string or a file) and converts it to uppercase hexadecimal format
+ (same as \pdfescapehex).
+ - \pdffiledump [offset <int>] [length <int>] <general text>
+ Expands to a hex dump of the file given in <general text>, starting at
+ given offset or 0 with given length.
+ - \pdfshellescape is a read-only integer that is 1 if \write18 is enabled, 0
+ otherwise.
+ - \pdfxformname <object number>, which expands to the number in the
+ corresponding form XObject name.
+ - \leftmarginkern <box number> and \rightmarginkern <box number> tell the
+ margin kern at the left and right side of the horizontal list stored in box
+ <box number>.
+ - \pdfpkmode is a token register that sets the MF mode for pixel font
+ generation. The contents of this register is dumped into the format, so one
+ can (optionally) preset it e.g. in part of pdftexconfig.tex.
+ - \pdftracingfonts: An integer variable controlling the tracing of font
+ expansion. It is zero by default; then we get a log (with fontexpansion)
+ like this
+ ...\tenrm t
+ ...\tenrm (+20) e
+ Without font expansion, this default should be compatible with TeX's
+ original log output.
+ If \pdftracingfonts is set to 1 (or greater), we get a more verbose log:
+ ...\xivtt (cmtt10@14.0pt) t
+ ...\xivtt (cmtt10+20@14.0pt) e
+ See also bug 304.
+- New experimental primitives:
+ - \pdfmatch [icase] [subcount <number>}] {<pattern>}{<string>}
+ Implements pattern matching using the POSIX regex.
+ It returns the same values as \pdfstrcmp, but with the following semantics:
+ -1: error case (invalid pattern, ...)
+ 0: no match
+ 1: match found
+ Options:
+ * icase: case insensitive matching
+ * subcount: it sets the table size for found subpatterns.
+ A number "-1" resets the table size to the start default.
+ - \pdflastmatch <number>
+ The result of \pdfmatch is stored in an array. The entry "0" contains the
+ match, the following entries submatches. The positions of the matches are
+ also available. They are encoded:
+ <position> "->" <match string>
+ The position "-1" with an empty string indicates that this entry is not
+ set.
+ - \pdfstrcmp{<a>}{<b>} compares two strings and returns the strings "0" if
+ <a> equals <b>, "-1" if <a> is less than <b>, "1" if <a> is greater than
+ <b>
+- The primitive \pdfmovechars has been removed (bug 294)
+- Bugfixes:
+ - empty strings are not supressed anymore (bug 335)
+ - \unhboxing and character protusion didn't work well together (bug 292)
+ - --jobname didn't work if there was no filename at all (bug 302)
+ - Some problem with fonts on solaris (bug 315)
+ - Dangling font objects with non-replacable fonts (bug 311).
+ - \pdfxform didn't work with box>255 (bug 310)
+ - cmap: unicode ???? is mapped to multiple glyphs (bug 306).
+- pdfTeX uses zlib 1.2.3
+
+------------------------------------------------
+pdfTeX 3.141592-1.21a was released on 2005-02-04
+------------------------------------------------
+- ttf2afm 1.0:
+ - added support for refering to glyphs via unicode in encoding files (ie 'uniXXX')
+ - added some more info to the AFM output
+ - some minor bug fixes
+ - a short documentation available
+- pdftex now understand forms 'uniXXXX' in encoding files (only makes sense
+ with TrueType fonts)
+- added subset tag for TrueType fonts
+- PDF strings are now printed as following:
+ (This is a string) -> (This is a string)
+ This is a string -> (This is a string)
+ <a1b245c1a2...> -> <a1b245c1a2...>
+- check for double newline char to get rid of empty lines in PDF output
+- Fixed a bug in the scanning of map lines introduced in the fix of bug #242 in
+ 1.20b.
+- Fixed three problems in xpdf; xpdf is now 3.00pl3
+- \ifeof18 is a simple method to test if \write18 is enabled.
+- a few extensions in pdfxtex:
+ - \pdflastximagecolordepth returns the last color depth
+ - \pdfximage supports a keyword "colorspace" following an object number
+ representing a ColorSpace object
+ - \pdfstrcmp compares two strings
+ - \pdfescapestring/\pdflastescapedstring provide a way to escape string
+ - \pdffirstlineheight/\pdflastlinedepth/\pdfeachlineheight/\pdfeachlinedepth
+ allow fixing line dimen
+ - patches from Taco
+ - px dimen unit
+ - tagcode patch
+ - quitvmode patch
+
+------------------------------------------------
+pdfTeX 3.141592-1.20b was released on 2004-12-22
+------------------------------------------------
+- Fixed some minor bugs, mostly with hz
+- The info line "output format initialized to PDF/DVI" isn't shown anymore, as
+ this info wasn't reliable (bug 112).
+- Now the PDF-related statistics (PDF objects...) in the .log file is only
+ shown in PDF output mode. It start with a line "PDF statistics:".
+- \pdfimageresolution is not limited to 2400 [dpi] anymore, can now be between
+ 0 and 65535 [dpi].
+- pdfTeX uses xpdf 3.00pl2
+- pdfTeX uses libpng 1.2.8, which fixes some png-related bugs.
+
+------------------------------------------------
+pdfTeX 3.141592-1.20a was released on 2004-09-06
+------------------------------------------------
+- There is a new program pdfxtex, which contains experimental features which
+ might end up in pdftex in the future.
+- Most distributions now use eTeX as the default engine, so when you call
+ pdftex you will get pdfeTeX. Most distributions now also use pdfTeX as the
+ default engine, so when you call latex you will get pdfeTeX running LaTeX.:-)
+- We are setting up pdfTeX as a project at sarovar
+ (http://sarovar.org/projects/pdftex/). Please report bugs etc. through the
+ site.
+- Support for the file pdftex.cfg is gone completely. All parameters that had
+ previously been set by it can be set through primitives; their values are
+ dumped to the format file.
+- The searchpath for encoding and mapfiles has been changed.
+ See http://tug.org/pipermail/tex-live/2004-January/004734.html and
+ http://tug.org/pipermail/tex-live/2004-January/004791.html
+- eTeX is now version 2.2, incorporating the last changes to TeX (3.141592).
+- New options for \pdfmapfile:
+ General functionality: Map items (map files, new: also single map lines; see
+ \pdfmapline) are put in list of pending map items. During the next shipout,
+ pending map items are sequentially scanned for their map entries, and an
+ internal map entry database is updated, using the modes below. Then the list
+ of pending map items is cleared. Map entries of fonts already in use are left
+ untouched. New: All \pdfmapfile and \pdfmapline commands can also be given
+ after shipout of the first page.
+ - \pdfmapfile {foo.map} clears the list of pending map items and starts a new
+ list with the only pending file foo.map. When the map entry lines of
+ foo.map are scanned, duplicate map entries are ignored and a warning is
+ issued. This is the old behaviour.
+ - \pdfmapfile {+foo.map} puts foo.map in the list of pending map items. When
+ the map entry lines of foo.map are scanned, duplicate map entries are
+ ignored and a warning is issued.
+ - \pdfmapfile {=foo.map} puts foo.map in the list of pending map items. When
+ foo.map is scanned, matching map entries in database are replaced by new
+ entries from foo.map.
+ - \pdfmapfile {-foo.map} puts foo.map in the list of pending map items. When
+ foo.map is scanned, matching map entries are deleted from database.
+ - \pdfmapfile {} clears the list of pending map items. It does not affect map
+ entries already registered into the database. This is the old behaviour.
+- New command \pdfmapline {line}. It's like \pdfmapfile but here you can set
+ single map lines like in the map files directly. The modifiers (+-=) have the
+ same effect as with \pdfmapfile.
+- Simplified the handling of the 14 Type 1 "standard fonts" (Times,
+ Helvetica...): They are now more or less handled like any other Type 1 font.
+ See http://www.ntg.nl/pipermail/ntg-pdftex/2004-July/000648.html
+- hz: So far the font expansion feature required that the user must be able to
+ create expanded tfms (eg cmr10+10.tfm). Now font expansion can be used
+ without creating these tfms.
+ See http://www.ntg.nl/pipermail/ntg-pdftex/2004-May/000504.html
+- hz: Changed \pdffontexpand primitive --> the expand factor is now fixed to
+ 1000 and the argument is ignored. This will lead to spurious texts of "1000"
+ in your output if you compile old documents.
+- New command \pdftexbanner which returns a string with the full banner of the
+ current binary (e.g. "This is pdfTeX, Version 3.141592-1.20a (Web2C 7.5.3)
+ kpathsea version 3.5.3")
+- The PTEX.FullBanner key is now inserted in the document info dict instead of
+ the catalog. Newer versions of Acrobat display it.
+- Now includes support for encTeX.
+- Extended \pdfannot to use reserveobjnum/useobjnum
+ See http://www.ntg.nl/pipermail/ntg-pdftex/2004-March/000424.html
+- Bugfix: pdfTeX would read an .xpdfrc when including pdfs.
+ See http://tug.org/pipermail/pdftex/2004-March/004835.html
+- Bugfix: The strings in /ID would sometimes be empty.
+- Bugfix: Even when mapfiles or encodings or PostScript font files were
+ missing, pdfTeX still produced a (most often corrupt) pdf. Now it aborts with
+ an error in these cases.
+- numerous small bugfixes.
+- pdfTeX now uses the GNU libavl from Ben Pfaff for managing of fontmap
+ entries.
+- pdfTeX uses zlib 1.2.1
+- pdfTeX uses xpdf 3.00
+- pdfTeX uses libpng 1.2.7
+
+------------------------------------------------
+pdfTeX 3.141592-1.11b was released on 2003-10-06
+------------------------------------------------
+- Bugfix: The handling of /Rotate produced displaced images when /Rotate was 90
+ or 270.
+
+------------------------------------------------
+pdfTeX 3.141592-1.11a was released on 2003-08-02
+------------------------------------------------
+- New command \pdftrailer analogue to \pdfcatalog whose argument ends up in the
+ trailer dictionary.
+- The behaviour when an included pdf has a newer version than the one specified
+ with \pdfoptionpdfminorversion can be controlled by the new internal integer
+ \pdfoptionpdfinclusionerrorlevel: If it's 0, pdfTeX gives only a warning; if
+ it's 1, it raises an error.
+ This can also be set in pdftex.cfg with pdf_inclusion_errorlevel
+- The syntax for outlines has been extended to allow attributes:
+ <outline spec> --> <attr spec> <action spec> [count <number>] <general text>
+ See http://www.ntg.nl/pipermail/ntg-pdftex/2003-June/000165.html
+- The syntax of \pdfobj has been extended:
+ \pdfobj <object type spec> (h, v, m)
+ <object type spec> --> reserveobjnum
+ | [useobjnum <number>] [<attr spec>] [stream [<attr spec>]] <object contents>
+ <object contents> --> <file spec>
+ | <general text>
+ When the optional keyword `reserveobjnum' and `useobjnum' is not given, the
+ behaviour is unchanged.
+ See also http://tug.org/mailman/htdig/pdftex/2003-March/003814.html
+- Bugfix: /CreationDate didn't care for the timezone and could be fooled.
+ See http://www.ntg.nl/pipermail/ntg-pdftex/2003-July/000223.html
+- Bugfix: The translation of 8-bit characters in included pdfs that had their
+ eighth bit set sometimes got wrong because of a missing typecast.
+ See http://www.ntg.nl/pipermail/ntg-pdftex/2003-July/000216.html
+- Bugfix: pdfTeX -ini would crash with a minimal file because it didn't read
+ it's config and so didn't know anything about fonts.
+ See http://tug.org/pipermail/pdftex/2003-July/004262.html
+- Bugfix: \pdfstartlink would produce spurious /NewWindow entries. Also the
+ syntax of <action spec> and <goto-action spec> has been cleaned up.
+ See http://www.ntg.nl/pipermail/ntg-pdftex/2003-June/000167.html
+- Bugfix: \pdffontattr was not used for T3 fonts.
+ See http://tug.org/pipermail/pdftex/2003-June/004127.html
+- Bugfix: The cropbox of an included pdf would sometimes not be used.
+ See http://tug.org/pipermail/pdftex/2003-May/004037.html
+- pdfTeX uses xpdf 2.02
+
+------------------------------------------------
+pdfTeX 3.141592-1.10b was released on 2003-02-26
+------------------------------------------------
+- The numbers in transformation matrices are allways written with maximum
+ precision (see http://tug.org/pipermail/pdftex/2003-February/003596.html).
+- Incorporated the new version of TeX: 3.141592
+- Bugfix: Numbers in pdfs would sometimes be just a wee bit of (changed
+ implementation of pdftoepdf.convertNumToPDF).
+- Bugfix: When setting the /Producer, /Creator or /CreationDate keys with
+ /pdfinfo pdfTeX would also insert default values which caused duplicate keys
+ in the info dict (see
+ http://tug.org/pipermail/pdftex/2003-February/003524.html).
+- The reading of mapfiles is much faster (see
+ http://tug.org/pipermail/pdftex/2002-July/002843.html).
+- Bugfix: AR5 had problems with the CTM when displaying in "fit visible" mode
+ (see http://tug.org/pipermail/pdftex/2002-May/002688.html).
+- Bugfix: str_in_str had wrong indices (see
+ http://tug.org/pipermail/pdftex/2002-March/002367.html).
+- Bugfix: decimal_digits defaulted to 0, which caused problems with included
+ images when including pdfs (see
+ http://tug.org/pipermail/pdftex/2003-February/003518.html).
+ It now defaults to 4.
+- Bugfix: the type of included images was decided based only on the extensions;
+ now pdfTeX looks for magic bytes at the start of files (see
+ http://tug.org/pipermail/pdftex/2003-February/003519.html)
+
+-----------------------------------------------
+pdfTeX 3.14159-1.10a was released on 2003-01-16
+-----------------------------------------------
+- pdfTeX is now able to produce pdf1.4 (which is also the default) and has
+ almost complete support for including pdf1.4 files:
+ - Additional attributes like MetaData are copied from included pdfs.
+ - Currently the Page Group attribute (see sections 7.3.6 and 7.5.5 of the pdf
+ 1.4 reference) of included pdfs is NOT copied (as we don't know how to
+ handle this when imposing pdfs).
+ This means including pdfs with transparency features will work as long as
+ the included pdf doesn't use Page Groups; if it does, the result might not
+ be what is expected (One application known to use Page Groups is Adobe
+ Illustrator v9++). The distributed pdfTeX binaries will give a warning
+ about any occurance of a Page Group in an included pdf and ignore the Page
+ Group (thus producing syntactically correct pdfs but probably not the
+ intended output).
+ Acrobat 5++ and newer versions of Jaws display files without Page Groups
+ correctly, so this might not really be a problem.
+ See pdftoepdf.cc for preprocessor flags which allow this behaviour to be
+ changed (copying the Page Group (most likely producing incorrect pdf) or
+ treating Page Groups as errors).
+- The new primitive \pdfoptionpdfminorversion sets the pdf version of the
+ generated file and the latest allowed pdf version of included pdfs:
+ \pdfoptionpdfminorversion=3
+ tells pdfTeX to set the pdf version to 1.3 and allows only included pdfs with
+ versions <= 1.3 .
+ The default for \pdfoptionpdfminorversion is 4 for pdf 1.4
+ This must appear before any data is written to the generated pdf file, so
+ you should put it at the very start of your files.
+ This can also be set in pdftex.cfg with pdf_minorversion
+- 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.
+- The support for the inclusion of jpeg images has been extended to allow the
+ inclusion of JPEG/Exif files which are produced by digital photo cameras
+ (thanks to Hartmut Henkel).
+- The support for the inclusion of tif images has been removed as it was of
+ limited use (it worked only for gray-scale and rgb images) and produced wrong
+ results (all other images types where treated as rgb images).
+ Tif images can be converted on *nix on-the-fly to pngs with the help of
+ ImageMagick, epstopdf.sty or pdftex.def v0.4 or newer, and this rule:
+ \DeclareGraphicsRule{.tif}{png}{.png}{`convert #1 `basename #1 .tif`.png}
+- The extensions for pdf encryption have been removed, since they make the
+ pdfTeX code overly complex. Those needing pdf encryption are encouraged to
+ produce a standalone program for encrypting pdfs.
+- pdfTeX now writes a usage statistic about the pdfTeX specific memory to the
+ log.
+- numerous bugfixes, most of them in the inclusion of pdfs.
+- pdfTeX uses xpdf 2.01
+- pdfTeX uses libpng 1.2.5
+
+---------------------------------------------------------------------
+pdfTeX 3.14159-1.00a-pretest-20011127-ojmw was released on 2002-01-29
+---------------------------------------------------------------------
+
+----------------------------------------------------------------
+pdfTeX 3.14159-1.00a-pretest-20010806 was released on 2001-08-06
+----------------------------------------------------------------
+
+----------------------------------------------------------------
+pdfTeX 3.14159-1.00a-pretest-20010804 was released on 2001-08-04
+----------------------------------------------------------------
+
+$Id: //depot/Build/source.development/TeX/texk/web2c/pdftexdir/NEWS#86 $
+// vim: tw=79:ts=2:expandtab:autoindent
diff --git a/Master/texmf/doc/pdftex/README b/Master/texmf/doc/pdftex/README
new file mode 100644
index 00000000000..b855a68d22b
--- /dev/null
+++ b/Master/texmf/doc/pdftex/README
@@ -0,0 +1,90 @@
+pdfTeX
+======
+
+README for version 3.14159-1.30.4 of $Date: 2005/08/23 $
+========================================================
+
+This directory contains the version 1.30.4 of pdfTeX, an extended version of
+TeX that can create PDF directly from TeX source files and enhance the
+result of TeX typesetting with the help of PDF. When PDF output is not
+selected, pdfTeX produces normal DVI output, otherwise it produces PDF
+output that looks identical to the DVI output. An important aspect of this
+project is to investigate alternative justification algorithms, optionally
+making use of multiple master fonts.
+
+pdfeTeX is an even more extended version of TeX than pdfTeX because it is
+not based on TeX but on eTeX, an extended version of TeX.
+
+pdfTeX is based on the original TeX sources and Web2c, and has been
+successfully compiled on Unix, Win32 and DOS systems. It is still under
+development and features may change; it produces reasonable PDF code.
+
+See the file NEWS for changes to the program.
+
+Documentation about pdfTeX can be found at http://www.pdftex.org
+
+There is also a mailing list on pdfTeX; go to
+http://tug.org/mailman/listinfo/pdftex for more information about it. Its
+searchable archive can be found at http://tug.org/pipermail/pdftex/
+Please read http://www.catb.org/~esr/faqs/smart-questions.html before
+asking any questions on the pdfTeX mailing list.
+
+A mailing list for the developement of pdfTeX can be found at
+http://www.ntg.nl/mailman/listinfo/ntg-pdftex
+
+
+LEGAL ISSUES
+============
+
+pdfTeX is copyright (c) 1996-2005 Han The Thanh, <thanh@pdftex.org>
+
+pdfTeX is free software; you can redistribute it and/or modify it under the
+terms of the GNU General Public License as published by the Free Software
+Foundation; either version 2 of the License, or (at your option) any later
+version.
+
+pdfTeX is distributed in the hope that it will be useful, but WITHOUT ANY
+WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
+details.
+
+You should have received a copy of the GNU General Public License along
+with pdfTeX; if not, write to the Free Software Foundation, Inc., 59 Temple
+Place, Suite 330, Boston, MA 02111-1307 USA
+
+pdfTeX uses code from TeX; for these parts the original copyright by Don
+Knuth applies. See the source files for details.
+
+pdfeTeX uses code from eTeX; for these parts the original copyright by
+Peter Breitenlohner applies. See the source files for details.
+
+
+WHAT TO DO IF YOU BELIEVE YOU HAVE FOUND A BUG IN pdfTeX
+========================================================
+
+Please read http://www.chiark.greenend.org.uk/~sgtatham/bugs.html and
+follow the guidelines there. Then go to the sarovar site of pdfTeX
+(http://sarovar.org/projects/pdftex/) and submit your bug report there.
+Here you can also report feature requests or patches.
+
+
+CONTRIBUTORS
+============
+
+Peter Breitenlohner, Ricardo Sanchez Carmenes, Otfried Cheong, Thomas
+Esser, Hans Hagen, Hartmut Henkel, Taco Hoekwater, Pawel Jackowski, Tom
+Kacvinsky, Akira Kakuto, Reinhard Kotucha, Derek B. Noonburg, Heiko
+Oberdiek, Jiri Osoba, Fabrice Popineau, Sebastian Rahtz, Tomas Rokicki,
+Martin Schröder, Petr Sojka, Olaf Weber, Jiri Zlatuska.
+
+pdfTeX is built on top of TeX, written by Donald Knuth cum suis (Liang and
+so), and eTeX, written by Peter Breitenlohner cum suis; part of the
+paragraph optimization is inspired by the work of Hermann Zapf.
+
+
+------------------------------------------------------------------------------
+
+Please send bug reports, offers of help, etc. to martin@pdftex.org
+
+$Id: //depot/Build/source.development/TeX/texk/web2c/pdftexdir/README#30 $
+// vim: tw=75
diff --git a/Master/texmf/doc/pdftex/manual/makefiles.cmd b/Master/texmf/doc/pdftex/manual/makefiles.cmd
new file mode 100644
index 00000000000..5bda71136c3
--- /dev/null
+++ b/Master/texmf/doc/pdftex/manual/makefiles.cmd
@@ -0,0 +1,13 @@
+rem texexec --format=plain pdftex-x
+rem copy pdf file to pdftex-y and edit that file
+rem texexec --format=plain pdftex-z
+
+texexec --pdf --result=pdftex-a pdftex-t
+texexec --pdf --result=pdftex-b pdftex-a --pdfarrange --print=up --paper=A4A3 --addempty=1,2
+
+texexec --pdf --result=pdftex-l pdftex-t --mode=letter
+texexec --pdf --result=pdftex-s pdftex-t --mode=screen
+
+del /q pdftex.zip
+
+zip pdftex pdftex-a.pdf pdftex-l.pdf pdftex-s.pdf pdftex-t.tex pdftex-i.tex pdftex-t.txt makefiles.cmd
diff --git a/Master/texmf/doc/pdftex/manual/pdftex-t.tex b/Master/texmf/doc/pdftex/manual/pdftex-t.tex
new file mode 100644
index 00000000000..3dbb8048258
--- /dev/null
+++ b/Master/texmf/doc/pdftex/manual/pdftex-t.tex
@@ -0,0 +1,4833 @@
+% interface=english modes=letter,screen output=pdftex
+% vim: tw=79
+
+% $Id: pdftex-t.tex,v 1.624 2005/10/23 23:28:37 hhenkel Exp $
+
+% The number of lines on the titlepage depends on the kind of
+% \PDF\ code that \PDFTEX\ generates.
+
+\setvariables[pdftex][titlepagelines=63]
+
+%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.624 2005/10/23 23:28:37 hhenkel Exp $
+
+\def\currentpdftex{1.30.4}
+
+%***********************************************************************
+
+\def\eTeX{{$\varepsilon$}-\kern-.125em\TeX}
+\def\eg{e.\,g.}
+\def\Eg{E.\,g.}
+
+\abbreviation [AFM] {afm} {Adobe Font Metrics}
+%\abbreviation [AMIGA] {Amiga} {Amiga hardware platform}
+%\abbreviation [AMIWEB] {AmiWeb2c} {\AMIGA\ distribution}
+\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 [JPEG] {jpeg} {Joint Photographic Expert 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 [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 [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]
+
+% 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.
+
+\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.}
+
+%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]
+
+\definetype
+ [esctype]
+\setuptype
+ [esctype]
+ [option=commands,escape=@]
+
+\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}]
+
+\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.5cm]
+
+\start
+
+ \chardef\fontdigits=2
+ \switchtobodyfont[10pt,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
+
+ \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, \PDFTEX\ also
+is available as \PDFETEX. Although in this document we will speak of
+\PDFTEX, we advise users to use \PDFETEX\ when available. That way they
+get the best of all worlds and are ready for the future. Starting with
+\TEXLIVE\ 2004, that future has arrived: \PDFETEX\ is now the primary
+\TEX\ engine.
+
+Other extensions to \PDFTEX\ are \MLTEX\ and \ENCTEX; recent \PDFTEX\
+engines have these often included.
+
+\PDFTEX\ is maintained by \THANH, Martin Schr\"oder, Hans Hagen,
+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||2005 \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 consist of objects. These objects can be recognized by their
+number and keywords:
+
+\starttyping
+7 0 obj << /Type /Catalog /Pages 5 0 R >> endobj
+\stoptyping
+
+Here \typ{7 0 obj ... endobj} is the object capsule. The first number is
+the object number. Later we will see that \PDFTEX\ gives access to this
+number. 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 file, while \type{\pdflastobj} returns the
+number \PDFTEX\ assigned to this object. 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. The version numbers permit a~roll||back. (An
+example of a~graphic editor that uses \PDF\ as storage format is the
+Adobe Illustrator.)
+
+In general this rather direct way of pushing objects in the files 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. Unless such
+direct objects are part of something larger, they will end up as isolated
+entities, not doing any harm but not doing any good either.
+
+When a~viewer opens a~\PDF\ file, it first goes to the end of the file. There
+it finds the keyword \type{startxref}, the signal where to look for the so
+called \quote {object cross reference table}. This table provides fast access
+to the objects that make up the file. The actual starting point of the file
+is defined after the \type{trailer}. The \type{/Root} entry points to the
+catalog. In this catalog the viewer can find the page list. In our example we
+have only one page. The trailer also holds an \type{/Info} entry, which tells
+ a~bit more about the document. Just follow the thread:
+
+\startnarrower
+\type{/Root} $\longrightarrow$ object~7 $\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 are 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}. Let's take a~closer look at this stream
+in object~3. Often 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~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 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, the words comes out rather fragmented, mainly because
+a~lot of kerning takes place. \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.
+
+This one page example uses an Adobe Times||Roman font. This is one of
+the 14 so||called standard fonts that are always present in the viewer
+application, and therefore need not be embedded in the \PDF\ file.
+However, when we use for instance Computer Modern Roman, we have to
+make sure that this font is available, and the best way to do this is
+to embed it. Just let your eyes follow the object thread and see how
+ a~font is described. The only thing removed from this example is the
+(partially) embedded glyph description file, which for the 14 standard
+fonts is not needed.
+
+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. 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,
+\FPTEX, \MIKTEX, 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 two separate
+distributions that contain \PDFTEX, both in \from[win32]: \FPTEX\ by
+Fabrice Popineau and \MIKTEX\ by Christian Schenk. 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 binary of \PDFTEX\ 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\ \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
+\stopesctyping
+
+The binaries \filename{pdftex} and \filename{pdfetex} are then
+built in the subdirectory \filename{build/texk/web2c}. In the same
+directory also the corresponding pool files \filename{pdftex.pool}
+and \filename{pdfetex.pool} are generated, that are needed for creating
+formats.
+
+%***********************************************************************
+
+\subsection{Placing files}
+
+The next step is to put the freshly compiled binaries and pool
+files into their proper places within the \TDS\ structure
+of the \TEX\ system. Put the files \filename{pdftex} and
+\filename{pdfetex} into the directory (\eg\ for a~typical \TETEX\ system)
+\filename{/usr/local/teTeX/bin/i686-pc-linux-gnu}, and the pool files
+into \filename{/usr/local/teTeX/share/texmf/web2c}.
+
+Don't forget to do a~\filename{texconfig-sys init} afterwards,
+so that all formats are regenerated system-wide with the fresh binaries.
+
+%***********************************************************************
+
+\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~\TETEX\ 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 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{pdfetex 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} Search path for TrueType font (\type{.ttf})
+files. Like Type~1 fonts, TrueType 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{\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}
+
+Both \PDFTEX\ and \PDFETEX\ engines 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. Often the \PDFTEX\
+program is a~mere link to the \PDFETEX\ engine; then also a~\PDFTEX\
+call generates an extended format.
+
+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
+pdfetex -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 tells the
+\PDFETEX\ engine to go into extended \type{-ini} mode; otherwise it
+stays in non||extended mode. The \PDFTEX\ engine can't be brought into
+extended mode at all; it interprets an asterisk \type{*} in front
+of a~file name as part of the file name. So, if you want a~\PDFLATEX\
+format with \PDF\ output and \ETEX\ extensions available (format file
+\filename{pdfelatex.fmt}), you would need to type \eg:
+
+\starttyping
+pdfetex -ini -jobname=pdfelatex *pdflatex.ini
+\stoptyping
+
+In \CONTEXT\ the generation depends on the interface used. A~format using the
+English user interface is generated with
+
+\starttyping
+pdfetex -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 {example.tex}. Process this file
+by typing:
+
+\starttyping
+pdftex example
+\stoptyping
+
+If the installation is ok, this run should produce a~file called \filename
+{example.pdf}. The file \filename {example.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} or
+ \type{pdfetex.pool} when you use \PDFETEX.
+
+\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 \TETEX\ then run \type{texconfig-sys init}.
+
+\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 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
+
+%MS it would be nice if we could get the number of objects directly from TeX,
+%MS but currently even the line given at the end of the log "PDF objects out
+%MS of" is only a minimum as it doesn't include all the objects from the page
+%MS tree and document info...
+Normally the page content takes one object. This means that one seldom finds
+more than a~few hundred objects in a~simple file. This document for instance
+uses about 900 objects. In demanding applications this number can grow quite
+rapidly, especially when one uses a~lot of widget annotations, shared
+annotations or other shared things. In these situations in \filename
+{texmf.cnf} one can enlarge \PDFTEX 's internal object table by adding a~line
+in \filename {texmf.cnf}, for instance:
+
+\starttyping
+obj_tab_size=400000
+\stoptyping
+
+%***********************************************************************
+
+\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, but a~source must be
+available for all fonts used in the document, except for the 14 standard
+fonts supplied by the \PDF\ reader (Times, Helvetica, Courier, Symbol
+and Dingbats). 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 downloading, 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 base (\POSTSCRIPT) font name. The {\em basename} field is
+checked against the BaseName entry of fonts coming with embedded \PDF\
+files. If there is a~match, the font will be removed from the embedded
+file, and a~local font is opened, which will contain the glyphs from the
+embedded file. This collecting mechanism helps keeping the resulting \PDF\
+file size small, if many files with similar fonts are to be embedded.
+Therefore it is recommended always to set the {\em basename} field.
+
+If a~{\em basename} field is given, also a~{\em fontfile} field must
+be there, unless the {\em basename} matches one of the 14 standard font
+names; then the {\em fontfile} field is optional. If the {\em fontfile}
+name is given, this font will be embedded (depending on flags, see below).
+If the {\em fontfile} name for a~standard font is missing, the font will
+be quietly left out, which is fine, as \PDF\ viewers will later render
+the text with their own versions of the font.
+
+\stopdescription
+
+\startdescription {fontflags}
+
+specify some characteristics of the font. The following description of
+these flags is taken, with slight modification, from the \PDF\ Reference
+Manual (the section on font descriptor flags). Viewers can adapt their
+rendering to these flags, especially when they substitute a~replacements
+for not embedded fonts.
+
+\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 font flags are 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 {encoding}
+
+specifies the name of the file containing the external encoding vector to be
+used for the font. The file name may be preceded by a~\type{<}, but the
+effect is the same. 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. It may be omitted if you are sure that the font
+resource has the correct built||in encoding. In general this option is highly
+preferred and is {\em required} when subsetting a~TrueType font.
+
+\stopdescription
+
+\startdescription {fontfile}
+
+sets the name of the font source file. This must be a~Type~1 or TrueType font
+file. The font file name can be preceded by one or two special characters,
+which says how the font file should be handled.
+
+\startitemize
+
+\item If the font file name is preceded by a~\type{<} the font file
+ will be partially downloaded, meaning that only used glyphs
+ (characters) are
+ embedded to the font. 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. Partial 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 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 not recommended. It might 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 If nothing precedes the font file name, the font file is read but
+ nothing is embedded, only the font parameters are extracted to
+ generate the so||called font descriptor, which is used by the \PDF\
+ reader to simulate the font if needed. This option is useful only when
+ you do not want to embed the font (i.\,e.~to reduce the output size),
+ but wish to use the font metrics and let the \PDF\ reader 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 downloading
+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 downloaded 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 a~some example lines.
+First we use two fonts from the 14 standard fonts with font||specific
+encoding, i.\,e.~no external encoding is given. In the first line, the
+fontfile is missing, so viewers will use their own font. The ZapfDingbats
+font is taken from the given font file.
+
+\starttyping
+psyr Symbol
+pzdr ZapfDingbats <pzdr.pfb
+\stoptyping
+
+Similarly, two standard fonts with an external encoding. The \type{<}
+preceding the encoding file name may be left out.
+
+\starttyping
+ptmr8r Times-Roman <8r.enc
+ptmri8r Times-Italic <8r.enc <ptmri8a.pfb
+\stoptyping
+
+ A~SlantFont is specified similarly as for \type{dvips}. The \type
+{SlantFont} or \type{ExtendFont} entries work only with embedded
+font files.
+
+\starttyping
+psyro ".167 SlantFont" <usyr.pfb
+pcrr8rn Courier ".85 ExtendFont" <8r.enc <pcrr8a.pfb
+\stoptyping
+
+Partially download a~font without re||encoding:
+
+\starttyping
+pgsr8a GillSans <pgsr8a.pfb
+\stoptyping
+
+Download a~font entirely without re||encoding:
+
+\starttyping
+pgsr8a GillSans <<pgsr8a.pfb
+\stoptyping
+
+Partially download a~font with re||encoding:
+
+\starttyping
+pgsr8r GillSans <8r.enc <pgsr8a.pfb
+\stoptyping
+
+Entirely download a~font with re||encoding:
+
+\starttyping
+pgsr8r GillSans <8r.enc <<pgsr8a.pfb
+\stoptyping
+
+Sometimes we do not want to include a~font, but need to extract parameters
+from the font file and re||encode the font as well. This only works for
+fonts with Adobe Standard Encoding. The font flags specify how such
+a~font looks like, so \eg\ the Adobe Reader can generate a~similar instance
+if the font resource is not available on the target system.
+
+\starttyping
+pgsr8r GillSans 32 <8r.enc pgsr8a.pfb
+\stoptyping
+
+Do not embed the font --- only extract the font parameters:
+
+\starttyping
+pgsr8a GillSans 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
+
+\subsection{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.624 2005/10/23 23:28:37 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 {\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}
+}
+
+\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}
+}
+
+\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}
+}
+
+% Currently it's only experimental, so don't really document it
+\iffalse
+\Syntax {
+\Tex {\pdfstrcmp} \Something{general text} \Something{general text} \Whatever{expandable}
+}
+\fi
+
+\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}
+}
+
+\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 {\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 {\pdfliteral} \Optional{\Literal {direct}} \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}
+}
+
+\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{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:}
+}
+
+\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 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 {\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 \esctype{pdfTeX-@currentpdftex} or \esctype{pdfeTeX-@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 \PDF\ Reference.
+
+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 (pdfeTeX @currentpdftex)
+ /Author (Tom and Jerry)
+ /CreationDate (D:20050428154343+01'00')
+ /ModDate (D:20050428155343+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 \PDF\ Reference Manual,
+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\ downloads 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 in this font as
+much as 3\,\% or shrink them by 2\,\%}. Because \PDFTEX\ uses internal
+data structures with fixed widths, each additional width also means an
+additional font. For practical reasons \PDFTEX\ uses discrete steps,
+in this example, 1\,\%. This means that for font \type{sometfm} up to~6
+differently scaled alternatives may be used. When no step is specified,
+0.5\,\% steps are used.
+
+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}.
+
+The additional expanded fonts get artificial names by adding the font
+expansion value to the tfmname of the base font, \eg\ \type{sometfm+10}
+for 1\,\% stretch or \type {sometfm-15} for 1.5\,\% shrink. If the
+\type{autoexpand} option is not given, \TFM\ files with these names and
+appropriate dimensions must be available. So, each expanded variant
+of a~font must have its own \TFM\ file! Expanded \TFM\ names like
+\type{sometfm+10} must not be mentioned in the map file (but the \TFM\
+name of the base font without expansion must be there). When no \TFM\
+file can be found, \PDFTEX\ will try to generate it by executing the
+script \type{mktextfm}, where available and supported.
+
+The font expansion is greatly simplified, if the \type{autoexpand}
+option is there. Then no expanded \TFM\ file versions are needed;
+instead, \PDFTEX\ generates expanded copies of the unexpanded \TFM\
+data structures and keeps them in its memory.
+
+\PDFTEX\ requires only unexpanded Type~1 font files for font expansion,
+from which all expanded font versions are internally generated and
+included (subsetted) into the \PDF\ output file. To enable font
+expansion, don't forget to set \type{\pdfadjustspacing} to a~value
+greater than zero.
+
+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
+\PDF\ Reference Manual, 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 managing font map files, to make them known
+to \PDFTEX\ so that they can be read in. If no \type{\pdfmapfile}
+primitive is given, the default map file \filename{pdftex.map} will be
+read in by \PDFTEX.
+
+Normally there is no need for the \PDFTEX\ user to bother about the
+\type{\pdfmapfile} primitive, as the main \TEX\ distributions provide
+nice helper tools that automatically assemble the default font map file.
+One prominent tool example is the script \type{updmap} coming with \TETEX.
+
+The operation mode of the \type{\pdfmapfile} primitive is selected by
+a~flag letter (\type{+}, \type{=}, \type{-}, or omitted). This flag defines
+how a~map file is going to be handled, and how a~collision between an
+existing 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. The companion
+primitive \type{\pdfmapline} allows something similar, only that a~single
+map line for one font (instead of a~map file name) is given as argument.
+Here are two examples:
+
+\starttyping
+\pdfmapfile{+myfont.map}
+\pdfmapline{+ptmri8r Times-Italic <8r.enc <ptmri8a.pfb}
+\stoptyping
+
+The general map handling function is that map items, which are either map
+file names or single font map lines (in case of the \type{\pdfmapline}
+primitive) are put into an auxiliary list of pending map items. During
+the next page shipout, this list is processed and all pending map items
+are sequentially scanned for their map entries, and an internal map
+entry database is updated, using one of the modes described below. Then
+the list of pending map items is cleared. All \type{\pdfmapfile}
+and \type{\pdfmapline} commands can also be given after shipout of the
+first page.
+
+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.
+
+\type{\pdfmapfile{foo.map}} (\type{+}/\type{=}/\type{-} flags omitted)
+clears the list of pending map items and starts a~new list with the only
+pending file \type{foo.map}. When the file \filename{foo.map} is scanned,
+duplicate map entries are ignored and a~warning is issued. When this
+command is given at the beginning of a~\TEX\ run, the default map file
+\filename{pdftex.map} will {\em not} be read in. This is compatible
+with the former 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 this version
+of command, but instead type either \type{\pdfmapfile{+myfont.map}}
+or \type{\pdfmapfile{=myfont.map}}, as described below.
+
+\type{\pdfmapfile {+foo.map}} puts the file \filename{foo.map} into the
+list of pending map items. When the file \filename{foo.map} is scanned,
+duplicate map entries are ignored and a~warning is issued. This is
+compatible with the former behaviour.
+
+\type{\pdfmapfile {=foo.map}} puts the file \filename{foo.map} into the
+list of pending map items. When the file \filename{foo.map} is scanned,
+matching map entries in the database are replaced by new entries from
+\filename{foo.map}.
+
+\type{\pdfmapfile {-foo.map}} puts the file \filename{foo.map} into the
+list of pending map items. When the file \filename{foo.map} is scanned,
+matching map entries are deleted from the database.
+
+\type{\pdfmapfile {}} clears the list of pending map items. It does
+not affect map entries already registered into the database. This is
+compatible with the former behaviour. When this command is given at the
+beginning of a~\PDFTEX\ run, the default map file \filename{pdftex.map}
+will {\em not} be read in. This may help with quick program startup,
+if no fonts are required.
+
+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
+
+\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 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) allows
+quick checks of a~new font map entry, before writing it into
+a~map file.
+
+\type{\pdfmapline {}} clears the list of pending map items a~similar
+way as \type{\pdfmapfile{}} does. \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} for \JPEG, 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\ or \JPEG\ bitmaps and \PDF\ images.
+
+While working with \PDF\ image, \Something{page spec} allows to decide which
+page of the document is to be included. Starting from \PDFTEX\ 1.11 one may
+also decide which \PDF\ page box of the image is to be treated as a~final
+bounding box. If \Something{pdf box spec} is present, overrides default
+behaviour specified by \type{\pdfforcepagebox} parameter. Both options are
+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 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\ or \JPEG\ 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) 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 particularily 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}
+
+%***********************************************************************
+
+\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 \PDF\
+Reference Manual, 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 {\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{\Literal {direct}}
+\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 resets the
+transformation matrix 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}.
+
+% 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}.
+
+%***********************************************************************
+
+\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{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{Random numbers}
+
+\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{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{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 {\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.
+
+\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}
+
+%***********************************************************************
+
+\section{Graphics and color}
+
+\PDFTEX\ supports inclusion of pictures in \PNG, \JPEG, 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.
+
+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.
+
+%***********************************************************************
+
+\section{Limitations of \PDFTEX}
+
+\PDFTEX\ currently lacks a~colorstack.
+This can be overcome by the \type{pdfcolmk} package.
+
+%***********************************************************************
+
+\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
+ \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 \PDF\ reference manual 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 \PDF\
+reference. 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 pdfeTeX-\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[7pt]
+ \setuplayout[grid=yes]
+ \setupcolumns[n=3]
+\stopnotmode
+
+\startmode[screen]
+ \setupcolumns[n=2]
+\stopmode
+
+\startcolumns[tolerance=verytolerant,distance=12pt] \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 readers 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
diff --git a/Master/texmf/doc/pdftex/manual/pdftex-w.pdf b/Master/texmf/doc/pdftex/manual/pdftex-w.pdf
new file mode 100644
index 00000000000..e0d7c6a5afa
--- /dev/null
+++ b/Master/texmf/doc/pdftex/manual/pdftex-w.pdf
@@ -0,0 +1,66 @@
+%PDF-1.4
+%ÐÔÅØ
+3 0 obj <<
+/Length 147
+>>
+stream
+BT
+/F51 9.963 Tf 91.925 759.927 Td[(W)80(elcome)-250(to)-250(pdfT)]TJ 67.818 -2.241 Td[(E)]TJ 4.842 2.241 Td[(X!)]TJ 138.924 -654.747 Td[(1)]TJ
+ET
+endstream
+endobj
+2 0 obj <<
+/Type /Page
+/Contents 3 0 R
+/Resources 1 0 R
+/MediaBox [0 0 595.276 841.89]
+/Parent 5 0 R
+>> endobj
+1 0 obj <<
+/Font << /F51 4 0 R >>
+/ProcSet [ /PDF /Text ]
+>> endobj
+6 0 obj <<
+/Type /Encoding
+/Differences [ 0 /.notdef 1/dotaccent/fi/fl/fraction/hungarumlaut/Lslash/lslash/ogonek/ring 10/.notdef 11/breve/minus 13/.notdef 14/Zcaron/zcaron/caron/dotlessi/dotlessj/ff/ffi/ffl/notequal/infinity/lessequal/greaterequal/partialdiff/summation/product/pi/grave/quotesingle/space/exclam/quotedbl/numbersign/dollar/percent/ampersand/quoteright/parenleft/parenright/asterisk/plus/comma/hyphen/period/slash/zero/one/two/three/four/five/six/seven/eight/nine/colon/semicolon/less/equal/greater/question/at/A/B/C/D/E/F/G/H/I/J/K/L/M/N/O/P/Q/R/S/T/U/V/W/X/Y/Z/bracketleft/backslash/bracketright/asciicircum/underscore/quoteleft/a/b/c/d/e/f/g/h/i/j/k/l/m/n/o/p/q/r/s/t/u/v/w/x/y/z/braceleft/bar/braceright/asciitilde 127/.notdef 128/Euro/integral/quotesinglbase/florin/quotedblbase/ellipsis/dagger/daggerdbl/circumflex/perthousand/Scaron/guilsinglleft/OE/Omega/radical/approxequal 144/.notdef 147/quotedblleft/quotedblright/bullet/endash/emdash/tilde/trademark/scaron/guilsinglright/oe/Delta/lozenge/Ydieresis 160/.notdef 161/exclamdown/cent/sterling/currency/yen/brokenbar/section/dieresis/copyright/ordfeminine/guillemotleft/logicalnot/hyphen/registered/macron/degree/plusminus/twosuperior/threesuperior/acute/mu/paragraph/periodcentered/cedilla/onesuperior/ordmasculine/guillemotright/onequarter/onehalf/threequarters/questiondown/Agrave/Aacute/Acircumflex/Atilde/Adieresis/Aring/AE/Ccedilla/Egrave/Eacute/Ecircumflex/Edieresis/Igrave/Iacute/Icircumflex/Idieresis/Eth/Ntilde/Ograve/Oacute/Ocircumflex/Otilde/Odieresis/multiply/Oslash/Ugrave/Uacute/Ucircumflex/Udieresis/Yacute/Thorn/germandbls/agrave/aacute/acircumflex/atilde/adieresis/aring/ae/ccedilla/egrave/eacute/ecircumflex/edieresis/igrave/iacute/icircumflex/idieresis/eth/ntilde/ograve/oacute/ocircumflex/otilde/odieresis/divide/oslash/ugrave/uacute/ucircumflex/udieresis/yacute/thorn/ydieresis]
+>> endobj
+4 0 obj <<
+/Type /Font
+/Subtype /Type1
+/Encoding 6 0 R
+/BaseFont /Times-Roman
+>> endobj
+5 0 obj <<
+/Type /Pages
+/Count 1
+/Kids [2 0 R]
+>> endobj
+7 0 obj <<
+/Type /Catalog
+/Pages 5 0 R
+>> endobj
+8 0 obj <<
+/Producer (pdfeTeX-1.30.4)
+/Creator (TeX)
+/CreationDate (D:20051024013807+02'00')
+/PTEX.Fullbanner (This is pdfeTeX, Version 3.141592-1.30.4-2.2 (Web2C 7.5.5) kpathsea version 3.5.5)
+>> endobj
+xref
+0 9
+0000000000 65535 f
+0000000330 00000 n
+0000000219 00000 n
+0000000015 00000 n
+0000002284 00000 n
+0000002372 00000 n
+0000000398 00000 n
+0000002429 00000 n
+0000002478 00000 n
+trailer
+<< /Size 9
+/Root 7 0 R
+/Info 8 0 R
+/ID [<DEDA359EDAD4320634FF9A471637DD88> <DEDA359EDAD4320634FF9A471637DD88>] >>
+startxref
+2682
+%%EOF
diff --git a/Master/texmf/doc/pdftex/manual/samplepdf/pdfcolor.tex b/Master/texmf/doc/pdftex/manual/samplepdf/pdfcolor.tex
new file mode 100644
index 00000000000..f09ecbcb750
--- /dev/null
+++ b/Master/texmf/doc/pdftex/manual/samplepdf/pdfcolor.tex
@@ -0,0 +1,158 @@
+% Very simple macros to show how to use colors with pdftex
+
+\def\cmykGreenYellow{0.15 0 0.69 0}
+\def\cmykYellow{0 0 1 0}
+\def\cmykGoldenrod{0 0.10 0.84 0}
+\def\cmykDandelion{0 0.29 0.84 0}
+\def\cmykApricot{0 0.32 0.52 0}
+\def\cmykPeach{0 0.50 0.70 0}
+\def\cmykMelon{0 0.46 0.50 0}
+\def\cmykYellowOrange{0 0.42 1 0}
+\def\cmykOrange{0 0.61 0.87 0}
+\def\cmykBurntOrange{0 0.51 1 0}
+\def\cmykBittersweet{0 0.75 1 0.24}
+\def\cmykRedOrange{0 0.77 0.87 0}
+\def\cmykMahogany{0 0.85 0.87 0.35}
+\def\cmykMaroon{0 0.87 0.68 0.32}
+\def\cmykBrickRed{0 0.89 0.94 0.28}
+\def\cmykRed{0 1 1 0}
+\def\cmykOrangeRed{0 1 0.50 0}
+\def\cmykRubineRed{0 1 0.13 0}
+\def\cmykWildStrawberry{0 0.96 0.39 0}
+\def\cmykSalmon{0 0.53 0.38 0}
+\def\cmykCarnationPink{0 0.63 0 0}
+\def\cmykMagenta{0 1 0 0}
+\def\cmykVioletRed{0 0.81 0 0}
+\def\cmykRhodamine{0 0.82 0 0}
+\def\cmykMulberry{0.34 0.90 0 0.02}
+\def\cmykRedViolet{0.07 0.90 0 0.34}
+\def\cmykFuchsia{0.47 0.91 0 0.08}
+\def\cmykLavender{0 0.48 0 0}
+\def\cmykThistle{0.12 0.59 0 0}
+\def\cmykOrchid{0.32 0.64 0 0}
+\def\cmykDarkOrchid{0.40 0.80 0.20 0}
+\def\cmykPurple{0.45 0.86 0 0}
+\def\cmykPlum{0.50 1 0 0}
+\def\cmykViolet{0.79 0.88 0 0}
+\def\cmykRoyalPurple{0.75 0.90 0 0}
+\def\cmykBlueViolet{0.86 0.91 0 0.04}
+\def\cmykPeriwinkle{0.57 0.55 0 0}
+\def\cmykCadetBlue{0.62 0.57 0.23 0}
+\def\cmykCornflowerBlue{0.65 0.13 0 0}
+\def\cmykMidnightBlue{0.98 0.13 0 0.43}
+\def\cmykNavyBlue{0.94 0.54 0 0}
+\def\cmykRoyalBlue{1 0.50 0 0}
+\def\cmykBlue{1 1 0 0}
+\def\cmykCerulean{0.94 0.11 0 0}
+\def\cmykCyan{1 0 0 0}
+\def\cmykProcessBlue{0.96 0 0 0}
+\def\cmykSkyBlue{0.62 0 0.12 0}
+\def\cmykTurquoise{0.85 0 0.20 0}
+\def\cmykTealBlue{0.86 0 0.34 0.02}
+\def\cmykAquamarine{0.82 0 0.30 0}
+\def\cmykBlueGreen{0.85 0 0.33 0}
+\def\cmykEmerald{1 0 0.50 0}
+\def\cmykJungleGreen{0.99 0 0.52 0}
+\def\cmykSeaGreen{0.69 0 0.50 0}
+\def\cmykGreen{1 0 1 0}
+\def\cmykForestGreen{0.91 0 0.88 0.12}
+\def\cmykPineGreen{0.92 0 0.59 0.25}
+\def\cmykLimeGreen{0.50 0 1 0}
+\def\cmykYellowGreen{0.44 0 0.74 0}
+\def\cmykSpringGreen{0.26 0 0.76 0}
+\def\cmykOliveGreen{0.64 0 0.95 0.40}
+\def\cmykRawSienna{0 0.72 1 0.45}
+\def\cmykSepia{0 0.83 1 0.70}
+\def\cmykBrown{0 0.81 1 0.60}
+\def\cmykTan{0.14 0.42 0.56 0}
+\def\cmykGray{0 0 0 0.50}
+\def\cmykBlack{0 0 0 1}
+\def\cmykWhite{0 0 0 0}
+
+\def\GreenYellow{\pdfsetcolor{\cmykGreenYellow}}
+\def\Yellow{\pdfsetcolor{\cmykYellow}}
+\def\Goldenrod{\pdfsetcolor{\cmykGoldenrod}}
+\def\Dandelion{\pdfsetcolor{\cmykDandelion}}
+\def\Apricot{\pdfsetcolor{\cmykApricot}}
+\def\Peach{\pdfsetcolor{\cmykPeach}}
+\def\Melon{\pdfsetcolor{\cmykMelon}}
+\def\YellowOrange{\pdfsetcolor{\cmykYellowOrange}}
+\def\Orange{\pdfsetcolor{\cmykOrange}}
+\def\BurntOrange{\pdfsetcolor{\cmykBurntOrange}}
+\def\Bittersweet{\pdfsetcolor{\cmykBittersweet}}
+\def\RedOrange{\pdfsetcolor{\cmykRedOrange}}
+\def\Mahogany{\pdfsetcolor{\cmykMahogany}}
+\def\Maroon{\pdfsetcolor{\cmykMaroon}}
+\def\BrickRed{\pdfsetcolor{\cmykBrickRed}}
+\def\Red{\pdfsetcolor{\cmykRed}}
+\def\OrangeRed{\pdfsetcolor{\cmykOrangeRed}}
+\def\RubineRed{\pdfsetcolor{\cmykRubineRed}}
+\def\WildStrawberry{\pdfsetcolor{\cmykWildStrawberry}}
+\def\Salmon{\pdfsetcolor{\cmykSalmon}}
+\def\CarnationPink{\pdfsetcolor{\cmykCarnationPink}}
+\def\Magenta{\pdfsetcolor{\cmykMagenta}}
+\def\VioletRed{\pdfsetcolor{\cmykVioletRed}}
+\def\Rhodamine{\pdfsetcolor{\cmykRhodamine}}
+\def\Mulberry{\pdfsetcolor{\cmykMulberry}}
+\def\RedViolet{\pdfsetcolor{\cmykRedViolet}}
+\def\Fuchsia{\pdfsetcolor{\cmykFuchsia}}
+\def\Lavender{\pdfsetcolor{\cmykLavender}}
+\def\Thistle{\pdfsetcolor{\cmykThistle}}
+\def\Orchid{\pdfsetcolor{\cmykOrchid}}
+\def\DarkOrchid{\pdfsetcolor{\cmykDarkOrchid}}
+\def\Purple{\pdfsetcolor{\cmykPurple}}
+\def\Plum{\pdfsetcolor{\cmykPlum}}
+\def\Violet{\pdfsetcolor{\cmykViolet}}
+\def\RoyalPurple{\pdfsetcolor{\cmykRoyalPurple}}
+\def\BlueViolet{\pdfsetcolor{\cmykBlueViolet}}
+\def\Periwinkle{\pdfsetcolor{\cmykPeriwinkle}}
+\def\CadetBlue{\pdfsetcolor{\cmykCadetBlue}}
+\def\CornflowerBlue{\pdfsetcolor{\cmykCornflowerBlue}}
+\def\MidnightBlue{\pdfsetcolor{\cmykMidnightBlue}}
+\def\NavyBlue{\pdfsetcolor{\cmykNavyBlue}}
+\def\RoyalBlue{\pdfsetcolor{\cmykRoyalBlue}}
+\def\Blue{\pdfsetcolor{\cmykBlue}}
+\def\Cerulean{\pdfsetcolor{\cmykCerulean}}
+\def\Cyan{\pdfsetcolor{\cmykCyan}}
+\def\ProcessBlue{\pdfsetcolor{\cmykProcessBlue}}
+\def\SkyBlue{\pdfsetcolor{\cmykSkyBlue}}
+\def\Turquoise{\pdfsetcolor{\cmykTurquoise}}
+\def\TealBlue{\pdfsetcolor{\cmykTealBlue}}
+\def\Aquamarine{\pdfsetcolor{\cmykAquamarine}}
+\def\BlueGreen{\pdfsetcolor{\cmykBlueGreen}}
+\def\Emerald{\pdfsetcolor{\cmykEmerald}}
+\def\JungleGreen{\pdfsetcolor{\cmykJungleGreen}}
+\def\SeaGreen{\pdfsetcolor{\cmykSeaGreen}}
+\def\Green{\pdfsetcolor{\cmykGreen}}
+\def\ForestGreen{\pdfsetcolor{\cmykForestGreen}}
+\def\PineGreen{\pdfsetcolor{\cmykPineGreen}}
+\def\LimeGreen{\pdfsetcolor{\cmykLimeGreen}}
+\def\YellowGreen{\pdfsetcolor{\cmykYellowGreen}}
+\def\SpringGreen{\pdfsetcolor{\cmykSpringGreen}}
+\def\OliveGreen{\pdfsetcolor{\cmykOliveGreen}}
+\def\RawSienna{\pdfsetcolor{\cmykRawSienna}}
+\def\Sepia{\pdfsetcolor{\cmykSepia}}
+\def\Brown{\pdfsetcolor{\cmykBrown}}
+\def\Tan{\pdfsetcolor{\cmykTan}}
+\def\Gray{\pdfsetcolor{\cmykGray}}
+\def\Black{\pdfsetcolor{\cmykBlack}}
+\def\White{\pdfsetcolor{\cmykWhite}}
+
+\def\pdfsetcolor#1{\pdfliteral{#1 k}}
+\def\setcolor#1{\mark{#1}\pdfsetcolor{#1}}
+
+\pdfoutput=1
+\def\maincolor{\cmykBlack}
+\pdfsetcolor{\maincolor}
+
+\def\makefootline{
+ \baselineskip24pt
+ \line{\pdfsetcolor{\maincolor}\the\footline}}
+
+\def\makeheadline{%
+ \edef\M{\topmark}
+ \ifx\M\empty\let\M=\maincolor\fi
+ \vbox to 0pt{\vskip-22.5pt
+ \line{\vbox to8.5pt{}%
+ \pdfsetcolor{\maincolor}\the\headline\pdfsetcolor{\M}}\vss}%
+ \nointerlineskip}
diff --git a/Master/texmf/doc/pdftex/manual/samplepdf/pic.pdf b/Master/texmf/doc/pdftex/manual/samplepdf/pic.pdf
new file mode 100644
index 00000000000..4f20d12a6d0
--- /dev/null
+++ b/Master/texmf/doc/pdftex/manual/samplepdf/pic.pdf
Binary files differ
diff --git a/Master/texmf/doc/pdftex/manual/samplepdf/rgb.icc b/Master/texmf/doc/pdftex/manual/samplepdf/rgb.icc
new file mode 100644
index 00000000000..d9c712f6905
--- /dev/null
+++ b/Master/texmf/doc/pdftex/manual/samplepdf/rgb.icc
Binary files differ
diff --git a/Master/texmf/doc/pdftex/manual/samplepdf/samplepdf.0 b/Master/texmf/doc/pdftex/manual/samplepdf/samplepdf.0
new file mode 100644
index 00000000000..9622d8d13fd
--- /dev/null
+++ b/Master/texmf/doc/pdftex/manual/samplepdf/samplepdf.0
@@ -0,0 +1,24 @@
+%!PS-Adobe-3.0 EPSF-3.0
+%%BoundingBox: -2 -2 403 252
+%%HiResBoundingBox: -1.99992 -2 402.00008 252
+%%Creator: MetaPost 0.901
+%%CreationDate: 2005.06.23:1538
+%%Pages: 1
+%%BeginProlog
+%%EndProlog
+%%Page: 1 1
+ 0 0.6 0 setrgbcolor 0 4 dtransform truncate idtransform setlinewidth pop
+ [] 0 setdash 1 setlinecap 1 setlinejoin 10 setmiterlimit
+gsave newpath 400.00008 0 moveto
+388.05362 20.69193 369.76968 36.62247 350.00008 50 curveto
+236.22455 126.98863 70.53836 127.82376 0.00008 250 curveto
+-1 1 scale stroke grestore
+ 0 2 dtransform truncate idtransform setlinewidth pop
+gsave newpath 350.00008 50 moveto
+309.8453 199.85959 97.68582 152.31425 0.00008 250 curveto
+-1 1 scale stroke grestore
+gsave newpath 350.00008 50 moveto
+195.84702 50 37.96687 108.30608 0.00008 250 curveto
+-1 1 scale stroke grestore
+showpage
+%%EOF
diff --git a/Master/texmf/doc/pdftex/manual/samplepdf/samplepdf.tex b/Master/texmf/doc/pdftex/manual/samplepdf/samplepdf.tex
new file mode 100644
index 00000000000..a9e2d655774
--- /dev/null
+++ b/Master/texmf/doc/pdftex/manual/samplepdf/samplepdf.tex
@@ -0,0 +1,1161 @@
+% This example shows how to use pdfTeX primitives. High-level macros are provided
+% by macros packages like LaTeX or ConTeXt. We present basic set of commands,
+% extended with some more sophisticated issues (like MP to PDF conversion). All
+% the functionality other than provided by pdfTeX itself is commented by default.
+% Please follow the code below and uncomment fragments you want.
+
+% Many new features has been implemented since the first release of pdfTeX. To
+% make this sample version independent, we use compatibility sections.
+
+\def\ifversion#1.#2#3#4 {% 1.20, 1.30.0 ...
+ \ifnum\pdftexversion<#1#2#3
+ \notsupported
+ \else
+ \supported
+ \fi}
+
+\def\supported{\expandafter\iftrue}
+\def\notsupported{\expandafter\iffalse}
+
+\def\feature#1.#2#3#4#{\dofeature{#1#2#3}{#1.#2#3#4}}
+\long\def\dofeature#1#2#3#4\endfeature{%
+ \ifnum#1>\pdftexversion
+ #3 not supported by this version of \pdfTeX.\par
+ \else#4\fi}
+
+\def\pdfTeX{pdf\TeX}
+\def\primitive#1{{\tt\char92\relax#1}}
+\def\newpage{\null\vfill\eject}
+
+\parindent=0pt
+
+\input pdfcolor.tex % simple macros to use color with pdftex;
+ % color names derived from dvicolor.tex
+
+% Unless mentioned explicitly, the default values of new parameters
+% are: 1) zero for integer/dimension parameters; 2) empty for tokens
+% parameters.
+
+% In previous versions of pdfTeX, integer parameters took their corresponding
+% values from pdftex.cfg config file. Starting from pdfTeX 1.20, the config file
+% id not read at all. All the parameters are specified in TeX code, optionally
+% dumped into format file.
+
+\pdfoutput=1 % positive value turns on PDF output;
+ % this parameter can not be changed after the pdf
+ % output has been opened
+
+\pdfcompresslevel=0 % compression level for text and image; allowed
+ % values are 0..9;
+ % 0 = no compression
+ % 1 = fastest compression
+ % 9 = best compression
+ % 2..8 = something between
+ % numbers out of range will be fixed to the most
+ % closed allowed value. Recommended value for most
+ % cases is 6 or 7.
+
+\pdfdecimaldigits=3 % number of digits after decimal point for real
+ % number in pdf output; the larger value the
+ % better accuracy but also larger output size;
+ % allowed range of values is 0..4
+
+%\pdfmovechars=2 % 1 turns on moving lower chars 0..32 to higher
+ % slots for fonts with last char code < 128,
+ % 2 or larger even for fonts with last char code > 127
+ % (rather obsolete)
+
+\pdfpkresolution=300 % resolution for bitmap (PK) fonts; allowed values
+ % are 72..1200, default is 600
+
+\pdfuniqueresname=0 % positive value turns on prepending unique
+ % prefix for each named resources
+ % pdftex-0.14[ef] has a bug with this feature
+ % turned on
+
+% dimension parameters
+
+\pdfhorigin=1in % horizontal origin (offset);
+ % for common purposes it is advised to use
+ % \hoffset
+
+\pdfvorigin=1in % vertical origin (offset); similar to \pdfhorigin,
+ % advised to use \voffset
+
+
+\pdfpagewidth=8.5in % paper size of the pdf output (letter in this case)
+\pdfpageheight=11in
+
+\pdflinkmargin=1pt % margin added to dimensions of link (see below)
+
+\pdfdestmargin=10pt % margin added to dimensions of destination (see
+ % below)
+
+\pdfthreadmargin=1em % margin added to dimensions of bead in article thread
+ % (see below)
+
+% tokens registers
+
+\pdfpagesattr={/MyPageAttribute /MyValue}
+ % optional attributes for the root Pages object;
+ % all pages inherit these attributes
+
+\pdfpageattr={/MyPagesAttribute /MyValue}
+ % optional attributes for individual pages;
+ % attributes specified here overwrite any
+ % attributes given by `\pdfpagesattr' (see PDF spec for details)
+
+\pdfpageresources{/MyPageResourceAttribute /MyValue}
+ % optional page resources dict content
+
+% And some more parameters that need special care.
+
+\ifversion 1.30.0 \else
+ \let\pdfforcepagebox\pdfoptionalwaysusepdfpagebox
+\fi
+
+\pdfforcepagebox=0 % a page box of PDF inclusions to be used
+ % as a clipping area. Here we use default (CropBox)
+ % \pdfforcepagebox is a shortened synonym of
+ % obsolete \pdfoptionalwaysusepdfpagebox.
+
+\ifversion 1.30.0 \else
+ \let\pdfminorversion\pdfoptionpdfminorversion
+\fi
+
+\pdfminorversion=5 % version of created PDF files and allowed PDF inclusions.
+ % The default value is 4 that is enough in most cases (PDF 1.4).
+ % However, some pdfTeX features presented here requires
+ % PDF 1.5. Starting from pdfTeX 1.30.0, the command is called
+ % \pdfminorversion.
+
+
+
+\ifversion 1.30.0 \else
+ \let\pdfinclusionerrorlevel\pdfoptionpdfinclusionerrorlevel
+\fi
+
+\pdfinclusionerrorlevel=0 % If the version of included PDF is greater than
+ % the one being typeset, by default an error is issued.
+ % If \pdfinclusionerrorlevel is set to one, warning only
+ % (synonym of obsolete \pdfoptionpdfinclusionerrorlevel).
+
+\ifversion1.30.0
+\pdfimagehicolor=1 % enables 16-bit colors for PNG inclusions;
+ % defaults to 1 if \pdfminorversion>=5,
+\pdfimageapplygamma=1 % enables gamma correction for PNG inclusions,
+\pdfgamma=1000 % sets pdfTeX `device gamma,'
+\pdfimagegamma=2200 % sets image gamma, if can't be taken from the image itself.
+\fi % (see below for details).
+
+% Version of pdftex can be accessed via \pdftexversion and \pdftexrevision.
+
+This is version \the\pdftexversion\ (revision \pdftexrevision) of \pdfTeX.
+
+% Version of created PDF (and the highest allowed version of PDF inclusions)
+% can be controlled with \pdfminorversion. In pdfTeX versions below 1.30.0, the
+% primitive was called \pdfoptionpdfminorversion.
+
+This file is PDF version 1.\the\pdfminorversion.
+\bigskip
+
+% Font resource in the pdf output has the form
+% "/F<number> <object number> 0 R", where <number> is accessible via
+% \pdffontname and <object number> via \pdffontobjnum.
+
+Font \fontname\font\ has resource name tag
+\pdffontname\font\ and object number \pdffontobjnum\font\ in the PDF output.
+Font size is \pdffontsize\font.\par
+
+\feature 1.30.0 {Disabling ligatures}
+
+Ligatures: ffont, fint, flint\par
+{\font\noli=cmr10 at\pdffontsize\font
+ \pdfnoligatures\noli No ligatures: ffont, fint, flint}
+\bigskip
+
+\endfeature
+
+% \pdfincludechars can be used to ensure certain characters to be
+% included in the font file. Normally only used characters are
+% included (subset is created).
+
+\pdfincludechars\font{ABCDEF}
+
+% pdfTeX ignores \special's text if \pdfoutput is set, unless they have
+% prefix "pdf:" or "PDF:" (in this case the prefix is not written out, of
+% course). \pdfliteral is intended to replace \special in pdf output mode.
+
+Changing color can be done by inserting `raw' PDF code, like
+\pdfliteral direct{0 1 1 0 k} % switch color to red; using \pdfliteral is
+this. % recommended
+
+\special{PDF:0 g} % switch color back to black; \special can be
+ % used with prefix "pdf:" or "PDF:", optionally appended with
+ % "direct:"
+ % A `direct' keyword is optional; it ensures that what one
+ % types into \pdfliteral is inserted literally indeed.
+ % Otherwise pdfTeX moves the space origin to the place after
+ % the last types item on the page, inserts the user code and
+ % restores its internal position.
+
+A simple picture:
+\pdfliteral {q 1 j 0 1 0 rg 0 0 1 RG 0 0 10 10 re B Q}
+
+% Roughly speaking, pdfTeX typeset text having an origin in lower-left corner of
+% the page (native PDF space origin). \pdfliteral used without `direct' keyword
+% changes this position temporarily to the point user probably expect. Thanks to
+% that, the rectangle painted above appears in-line, not in the lower-left corner
+% of the page. If one say \pdfliteral{...}\pdfliteral{...}, pdfTeX makes the
+% offset only once; it moves to current point of the page before the first
+% literal content, and comes back after the last one.
+
+\bigskip
+
+% User-defined object can be inserted into the pdf output by \pdfobj. The
+% object is written out as specified, apart from case when \pdfobj is used with
+% "stream" option. An object created by \pdfobj is held in memory and will
+% not be written to the pdf output, unless 1) the object is referenced by
+% saying \pdfrefobj <object number>; or 2) \pdfobj is preceded by
+% \immediate. The object number of the last object created by \pdfobj is
+% accessible via \pdflastobj
+
+\pdfobj{Hello} % the simplest case
+\pdfrefobj \pdflastobj % mark the object to be written out; it can be
+ % understood as a reference to the object
+
+\immediate \pdfobj stream % create the object as a stream a write it to
+ {Hello} % the pdf output immediately
+
+\pdfobj stream % create the object as a stream with
+ attr {/MyStreamAttribute /MyValue} % additional attributes
+ {Hello}
+\pdfrefobj \pdflastobj
+
+\pdfobj file {obj.dat} % read the object contents from file obj.dat
+\pdfrefobj \pdflastobj
+
+\pdfobj stream % read the stream contents from file obj.dat
+ file {obj.dat}
+\pdfrefobj \pdflastobj
+
+\pdfobj stream % read the stream contents from file obj.dat
+ attr {/MyStreamAttribute /MyValue} % with additional attributes
+ file {obj.dat}
+\pdfrefobj \pdflastobj
+
+% \pdflastobj is always global, as all others \pdflast* read-only integers (see
+% below). PDF object numbers are unique within the document. One may notice, that
+% if \pdfobj is preceded by \immediate, \pdflastobj seems to return subsequent
+% values (i.e 5,6,7,8...). Since \pdfobj is not the only command that creates PDF
+% objects, one can't simply assume, that if current \pdflastobj returns 5, the
+% next one will always return 6. Thus, pdfTeX provides a forward-referencing
+% mechanism (introduced in pdfTeX 1.20).
+
+\feature 1.20 {Forward object referencing}
+
+\pdfobj reserveobjnum
+We have an access to PDF object numbers, even before defining those objects.
+\pdfobj useobjnum\pdflastobj {(This is object number \the\pdflastobj)}
+\pdfrefobj\pdflastobj
+
+\endfeature
+
+% TeX boxes can be written into so-called XObject form, which is very
+% similar to a normal page in the pdf output. Additional data can be
+% inserted to the XObject form dictionary itself as well as the Resource
+% dictionary of the XObject form
+
+\setbox0=\hbox{This is a box saved as a XObject form}
+\pdfxform
+ attr {/MyXObjectFormAttribute /MyValue}
+ resources {/MyXObjectFormResourceAttribute /MyValue}
+ 0
+
+% Similarly to \pdfobj, the object created by \pdfxform is held in memory
+% and is not written to the pdf output, unless 1) the object is referenced
+% by saying \pdfrefxform <object number>; or 2) \pdfxform is preceded by
+% \immediate. The object number of the last XObject form created
+% by \pdfxform is accessible via \pdflastxform. Note that
+% \immediate\pdfxform does not typeset anything; it just ensures that the
+% XObject form is written out to the output. To display the form, it is
+% necessary to say \pdfrefxform <object number> in the intended place.
+% Another point is that \pdfrefxform acts similarly rather to rules than to
+% boxes concerning dimensions and space setting. It's highly recommended to
+% wrap \pdfrefxform by a box in order to ensure spacing will be correct.
+
+\hbox{\pdfrefxform \pdflastxform}
+
+% Similarly to \pdflastobj, \pdflastxform returns the PDF object number assigned
+% for XObject form just created. pdfTeX also provides \pdfxformname primitive, that
+% returns a resource name identifier of the XObject written to PDF output with given
+% object number.
+
+XObject above has been written as object \the\pdflastxform.
+
+\feature 1.30.0 {Access to XObject names}
+
+Its resource name tag is \pdfxformname\pdflastxform\
+({\tt/Fm\pdfxformname\pdflastxform\ \the\pdflastxform\space 0 R}
+entry in page resources dictionary).
+
+\endfeature
+
+\bigskip
+
+% Thanks to Taco Hoekwater pdfTeX 1.30.0 and higher provides precise time
+% measuring mechanism. \pdfelapsedtime primitive returns the time elapsed from
+% the current run start. Time is measured in `scaled seconds' meaning that 65536
+% scaled seconds is 1 second. There is also \pdfresettimer primitive that causes
+% zeroing the internal clock.
+
+{\catcode`\p=12 \catcode`\t=12 \gdef\WITHOUTPT#1pt{#1}}
+ \def\withoutpt#1{\expandafter\WITHOUTPT#1} % returns float-like string
+
+\feature 1.30.0 {Precise timer}
+
+\dimen0=\pdfelapsedtime sp
+\pdfresettimer
+It took \withoutpt\the\dimen0 \ seconds to typeset the whole stuff above.
+To typeset the last two sentences it took \the\pdfelapsedtime\ `scaled seconds'
+(1s/65536).
+\bigskip
+
+\endfeature
+
+% Taco Hoekwater has also implemented random number support (introduced in 1.30.0)
+
+\feature 1.30.0 {Random numbers}
+
+Random seed initialized to \the\pdfrandomseed.
+\pdfsetrandomseed\dimen0 % just saved elapsed time
+We may change it, lets say to \the\pdfrandomseed.\par
+
+10 uniformly distributed random numbers [0..100]:
+\count100=0 \loop
+ \pdfuniformdeviate101
+ \advance\count100 by1
+ \ifnum\count100<10,
+\repeat.\par
+
+10 normally distributed random numbers:
+\count100=0 \loop
+ \dimen0=\pdfnormaldeviate sp
+ $\withoutpt\the\dimen0$%
+ \advance\count100 by1
+ \ifnum\count100<10,
+\repeat.\par
+
+\bigskip
+
+\endfeature
+
+% Starting from pdfTeX 1.30.0, there is an expandable string comparison in pdfTeX.
+% You can compare two strings lexicographically using \pdfstrcmp{<str1>}{<str2>}.
+% The command returns -1, 0, or 1 as a comparison result.
+% Both strings are expanded before being compared.
+% \feature 1.30.0 {String comparison}
+% \pdfstrcmp{a}{aa} returns -1 since 'a'<'aa'
+% \pdfstrcmp{aa}{aa} returns 0 since 'aa'='aa'
+% \pdfstrcmp{aaa}{abc} returns -1 since 'aaa'<'abc'
+% \pdfstrcmp{abc}{ABC} returns 1 since 'aaa'>'ABC'
+% \endfeature
+% This is still experimental, as well as regex support
+
+% Thanks to Heiko Oberdiek, starting from pdfTeX 1.30.0 a set of expandable
+% string handlers are available. \pdfescapestring converts its parameter into a
+% form readable for PDF interpreters, escaping those characters that can be used
+% in PDF string objects without quotation. Similarly, \pdfescapename converts its
+% argument into PDF name, replacing special PDF characters with their hexadecimal
+% representation preceded by `#'. \pdfescapehex takes an ASCII code of each
+% character of its argument and converts this number into hexadecimal form. Last
+% but not least, \pdfunescapehex treats each pair of characters as a hexadecimal
+% number and returns an ASCII characters of given codes. All those commands
+% expand their arguments before applying conversion.
+
+\feature 1.30.0 {PDF string handling}
+
+\def\sometext{Some text/(1)}
+If there is a text `{\tt\sometext}',\par
+in PDF string one should use {\tt(\pdfescapestring{\sometext}},\par
+and in PDF name it would be {\tt/\pdfescapename {\sometext}}.\par
+In hex form it looks like {\tt<\pdfescapehex{\sometext}>},\par
+but you can always reverse it to get {\tt\pdfunescapehex{\pdfescapehex{\sometext}}}.
+\bigskip
+
+\endfeature
+
+% Also handling external files has been greatly improved. Starting from pdfTeX 1.30.0
+% you can check external files modification date, file size and even md5 check sum.
+
+\feature 1.30.0 {External file handling}
+
+The source of this document is {\tt\pdffilesize{\jobname}} bytes long. Last modification date
+is {\tt\pdffilemoddate{\jobname}}. The md5 sum is {\tt\pdfmdfivesum{\jobname}}.
+Bytes 7 to 13 of the source are hex {\tt\pdffiledump offset 7 length 7{\jobname}}
+(string `\pdfunescapehex{\pdffiledump offset 7 length 7 {\jobname}}').
+
+\endfeature
+
+% \pdfsavepos saves coordinates of the current position on the page relative to
+% lower-left corner. \pdflastxpos and \pdflastypos are available while shipping
+% out the page. Both are integers; the position is expressed in scaled points.
+
+\pdfsavepos
+\write16{Position: X=\number\pdflastxpos sp, Y=\number\pdflastypos sp.}
+
+\newpage
+
+% pdfTeX 1.20 and higher allows to get the object number of already typeset page
+
+\feature 1.20 {Page object reference}
+
+The previous page has been written as object \pdfpageref1.
+
+\endfeature
+
+% Images can be included with pdftex using \pdfximage. Supported formats
+% are determined by file name extension:
+% .pdf/.PDF: PDF
+% .png/.PNG: PNG
+% .jpg/.JPG/.jpeg/.JPEG: JPEG
+%
+% Sorry, TIFF files are no longer supported.
+%
+% pdfTeX itself does not support EPS and Postscript codes at all, however
+% it's possible to include Metapost output. EPS files can be converted to
+% PDF for use with pdfTeX. See below for further info about using Metapost
+% and EPS.
+
+\pdfximage {pic.pdf} % read image pic.pdf (search for it in TEXINPUTS path)
+
+% It also possible to select which page to include. Pages are numbered from
+% 1. Out-of-range values are fixed to 1 and bitmapped images have always 1
+% page. To include let's say the 2nd page of a pdf image, one can use
+% \pdfximage page 2 {file.pdf}
+
+% Similarly to \pdfobj, the image created by \pdfximage is held in memory
+% and is not written to the pdf output, unless 1) the image is referenced
+% by saying \pdfrefximage <object number>; or 2) \pdfximage is preceded by
+% \immediate. The object number of the last image created by \pdfximage is
+% accessible via \pdflastximage. Note that \immediate\pdfximage does not
+% typeset anything; it just ensures that the image is written out to the
+% output. To display the image, it is necessary to say
+% \pdfrefximage <object number> in the intended place. Another point is
+% \pdfrefximage act similarly rather to rules than to boxes concerning
+% dimensions and space setting. In order to make images act as boxes
+% (concerning dimensions and spacing), it's necessary to wrap them into a
+% box.
+
+\hbox{\pdfrefximage \pdflastximage}
+
+% Since a pdf image may have more than 1 page, the number of the last image
+% opened by \pdfximage is accessible via \pdflastximagepages
+
+The last image has \the\pdflastximagepages\ page(s).
+
+% The dimensions of the image can be also controlled via <rule spec>. The
+% default values are zero for depth and `running' for height and width. If
+% all of them are given, the image will be scaled to fit the specified
+% values. If some of them (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 of them is given then
+% the image will take its natural size. An image inserted at its natural
+% size often has a resolution of \pdfimageresolution (or 72 if
+% \pdfimageresolution is set to zero) 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 original resolution.
+% The dimension of the image can be accessed by enclosing the \pdfrefximage
+% command to a box and checking the dimensions of the box.
+
+\pdfximage width 6cm {pic.pdf} % set the image width and keep the
+\pdfrefximage \pdflastximage % `nature' proportion width : height
+
+\pdfximage height 4cm {pic.png} % set the image height and keep the
+ % `nature' proportion width : height
+
+\edef\MyImg{\the\pdflastximage} % save the image number for later reuse
+\pdfrefximage\MyImg
+
+\pdfximage width 6cm height 4cm % set both image width and height; the
+ {pic.jpg} % final proportion width : height may be
+ % different from the `nature' one
+
+\pdfimageresolution=72 % to open an image at 72 dpi
+\pdfximage {pic.pdf}
+\setbox0=\hbox{\pdfrefximage\pdflastximage} % get dimensions of the image
+ % in order to include the image
+ % at a specific resolution
+\dimen0=.06\wd0 % calculate the image width at 1200 dpi (0.06 = 72/1200)
+\pdfximage % include the image at resolution 1200 dpi
+ width \dimen0 {pic.pdf} % by setting image width to the calculated value
+\pdfrefximage \pdflastximage
+
+\newpage
+
+% While embedding PDF image one may decide which area of the image (mediabox,
+% cropbox, bleedbox, trimbox or artbox) should be treated as a final (visible)
+% bounding box. There is \pdfoptionalwaysusepdfpagebox parameter that specifies
+% the default behaviour (1 for mediabox, 2 for cropbox, 3 for bleedbox, 4 for
+% trimbox and 5 for artbox). For sake of backward compatibility, if set to 0
+% cropbox is used. Starting from pdfTeX 1.30.0, a synonym \pdfforcepagebox is
+% used. One may also override the default settings by providing page box
+% specification in \pdfximage syntax. In example, \pdfximage trimbox {<file>}
+% causes clipping the image to the trimbox area. Obviously, those settings take an
+% effect only if the desired box page is defined in the image being included.
+% According to PDF spec, PDF page boxes act as follows:
+% mediabox % the entire page area (the only one always present)
+% cropbox % the visible page area (defaults to mediabox)
+% bleedbox % the page area with trimming margins (defaults to cropbox)
+% trimbox % the page area without bleeds (defaults to cropbox)
+% artbox % the logical page content (defaults to cropbox)
+
+% pdfTeX takes care about version of included PDF images. By default, an error is
+% issued if this version is newer than the PDF being created (controlled by
+% \pdfminorversion). If the \pdfoptionpdfinclusionerrorlevel is set to 0, only
+% warning is issued. Starting pdfTeX 1.30.0 \pdfinclusionerrorlevel synonym is used
+% instead.
+
+% Thanks to Taco Hoekwater pdfTeX 1.30.0 and higher provides advanced PNG
+% inclusions handling. Nonzero \pdfimagehicolor parameter enables embedding
+% of PNG images with 16 bit wide color channels at their full color resolution.
+% This functionality is automatically disabled if \pdfminorversion<5, and automatically
+% enabled if \pdfminorversion>=5
+% Another primitive -- \pdfimageapplygamma -- enables gamma correction of embedded
+% PNG files on the base of two parameters:
+% \pdfgamma % device gamma for pdfTex
+% \pdfimagegamma % image gamma (used if one can't be derived from the image)
+% Both values are integers measured in promile (1000 = gamma 1.0)
+% All the parameters of gamma correction have to be set before any data
+% is written to the PDF output; thus we put them at the very beginning of this sample.
+
+% \ifx\undefined\quitvmode % primitive `\leavevmode' introduced in pdfTeX 1.30.0
+% \let\quitvmode\leavevmode
+% \fi
+
+\pdfximage width8cm {pic16.png}%
+\pdfrefximage\pdflastximage
+The image had originally 16 bits-per-channel.
+
+\feature 1.21 {Image color depth info}
+Embedded one has \the\pdflastximagecolordepth\ bits-per-channel;
+\endfeature
+
+\feature 1.30.0 {16-bit color mode for PNG inclusions}
+the image has been read in 16-bit color resolution.
+\endfeature
+
+\feature 1.30.0 {Gamma correction}
+Try out different gamma parameters. % we have to set them before any data
+\endfeature % is written to the output
+
+\bigskip
+
+% From pdfTeX 1.21 \pdfximage command can be followed by `colorspace <objnum>',
+% where <objnum> is a number of user-defined color space object. Simply speaking,
+% we may instructs the viewer, how the image should be rendered. However, this
+% works only for JPEGs. Here we perform some sort of `color management' by
+% applying a color profile to the JPEG image.
+
+% Be aware; this is viewer dependent.
+
+\feature 1.21 {User-defined image color space hook}
+
+\immediate\pdfobj
+ stream
+ attr {/N 3 /Alternate /DeviceRGB}
+ file {rgb.icc} % color profile
+
+\immediate\pdfobj{[/ICCBased \the\pdflastobj\space 0 R]}
+
+\edef\objnum{\the\pdflastobj}
+
+\pdfximage width 8cm colorspace\objnum {pic.jpg}
+\pdfrefximage\pdflastximage
+The image is calibrated with ICC profile.
+
+\immediate\pdfobj
+ stream attr
+ {/FunctionType 4
+ /Domain [0 1 0 1 0 1]
+ /Range [0 1 0 1 0 1]}{{exch pop exch pop 0 exch 0 exch}}
+
+\immediate\pdfobj % don't treat it serious %)
+ {[/DeviceN [/Red /Green /Blue] /DeviceRGB \the\pdflastobj\space 0 R]}
+
+\edef\objnum{\the\pdflastobj}
+
+\pdfximage width8cm colorspace\objnum {pic.jpg}
+\pdfrefximage\pdflastximage
+Hacked image color space.
+
+\endfeature
+
+\newpage
+
+% Thanks to Hans Hagen pictures created by Metapost can be easily used with
+% pdftex. The following files come from ConTeXt distribution. Another
+% place to get them is http://www.tug.org/applications/pdftex/, where
+% is also possible to get the latest driver file for using LaTeX graphicx
+% package with pdftex.
+
+\input supp-mis.tex % supp-mis.tex is loaded by supp-pdf.tex
+\input supp-pdf.tex % automatically, so the above line could be left
+ % out (it's given here to make clear what all files
+ % are needed to use \convertMPtoPDF)
+
+% the figure cmr10.103 was created by running Metapost on cmr10.mf
+
+% \convertMPtoPDF {filename} {x scale} {y scale}
+\convertMPtoPDF{cmr10.103}{1}{1}
+\newpage
+
+% It is possible to have Metapost code inside the tex sources and call
+% Metapost to generate the figure before calling \convertMPtoPDF.
+
+% define some contants that will be used in the Metapost code
+\def\pointA{(50, 50)}
+\def\pointB{(400, 250)}
+
+\newwrite\mpfile % temporary file for metapost code
+\immediate\openout\mpfile = \jobname.mp
+
+\immediate \write \mpfile {%
+prologues := 1;
+def drawleaf(expr A, B, C) =
+ pickup pencircle scaled 4bp;
+ draw (0, 0) {dir 60} .. A .. {dir 60} B withcolor C;
+ pickup pencircle scaled 2bp;
+ draw A {dir 75} .. {dir 45} B withcolor C;
+ draw A {right} .. {dir 75} B withcolor C;
+enddef;
+beginfig(0);
+ drawleaf(\pointA, \pointB, .6green);
+ d := .5 xpart \pointB;
+ currentpicture := currentpicture reflectedabout ((d, 0), (d, 1));
+endfig;
+beginfig(1);
+ drawleaf(\pointA, \pointB, .6blue);
+ currentpicture := currentpicture reflectedabout (\pointA, \pointB);
+endfig;
+end;
+}
+\immediate \closeout \mpfile % close the file before running Metapost
+
+% Now we call Metapost to generate the ps output; this is system-dependent
+% and has been tested for web2c only. It is necessary to have
+%
+% shell_escape = t
+%
+% in texmf.cnf in order to run it.
+%
+% Starting from pdfTeX 1.21a, one may test if this option is enabled using
+% \ifeof condition (distribution dependent):
+
+\feature 1.21 {Shell escape detection (via \primitive{ifeof})}
+Shell escape (via \primitive{ifeof}) seems to be
+\ifeof18 disabled\else enabled\fi.
+\endfeature
+
+% ...pdfTeX 1.30.0 introduces its own primitive integer flag
+
+\feature 1.30.0 {Shell escape detection (via \primitive{pdfshellescape})}
+Shell escape (via \primitive{pdfshellescape}) seems to be
+\ifnum\pdfshellescape=1 disabled\else enabled\fi.
+\endfeature
+
+% Uncomment line below, if there is Metapost available in your system (should be!)
+% \immediate \write 18 {mpost \jobname.mp} % call Metapost on \jobname.mp
+\convertMPtoPDF{\jobname.0}{1}{1}
+\convertMPtoPDF{\jobname.1}{1}{1}
+
+\newpage
+
+% EPS pictures cannot be inserted directly by pdfTeX, but it's possible to
+% convert them to PDF using a Postscript-to-PDF converter, like Acrobat
+% Distiller or Ghostscript. The below example calls epstopdf (available
+% from http://www.tug.org/applications/pdftex), which preprocess the EPS
+% and afterwards uses Ghostscript to convert to PDF. In order to convert
+% EPS with embedded Type 1 fonts, a later version (beta) of Ghostscript is
+% required.
+
+% Uncomment line below, if there is epstopdf utility available in your system
+
+%\immediate \write 18 {epstopdf --outfile=tmp.pdf cmr10.103} % call epstopdf
+\pdfximage height \vsize {tmp.pdf} % insert the PDF converted from EPS
+\topskip=0pt
+\pdfrefximage \pdflastximage
+\newpage
+
+% some text to try using threads
+
+\def\text{%
+Ah! perhaps a burning match might be some good, if she could draw it from
+the bundle and strike it against the wall, just to warm her fingers. She
+drew one out---"scratch!" how it sputtered as it burnt! It gave a warm,
+bright light, like a little candle, as she held her hand over it. It was
+really a wonderful light. It seemed to the little girl that she was sitting
+by a large iron stove, with polished brass feet and a brass ornament. How
+the fire burned! and seemed so beautifully warm that the child stretched
+out her feet as if to warm them, when, lo! the flame of the match went out,
+the stove vanished, and she had only the remains of the half-burnt match in
+her hand.
+
+ She rubbed another match on the wall. It burst into a flame, and
+where its light fell upon the wall it became as transparent as a veil,
+and she could see into the room. The table was covered with a snowy
+white table-cloth, on which stood a splendid dinner service, and a
+steaming roast goose, stuffed with apples and dried plums. And what
+was still more wonderful, the goose jumped down from the dish and
+waddled across the floor, with a knife and fork in its breast, to
+the little girl. Then the match went out, and there remained nothing
+but the thick, damp, cold wall before her.
+
+ She lighted another match, and then she found herself sitting
+under a beautiful Christmas-tree. It was larger and more beautifully
+decorated than the one which she had seen through the glass door at
+the rich merchant's. Thousands of tapers were burning upon the green
+branches, and colored pictures, like those she had seen in the
+show-windows, looked down upon it all. The little one stretched out
+her hand towards them, and the match went out.
+
+ The Christmas lights rose higher and higher, till they looked to
+her like the stars in the sky. Then she saw a star fall, leaving
+behind it a bright streak of fire. "Some one is dying," thought the
+little girl, for her old grandmother, the only one who had ever
+loved her, and who was now dead, had told her that when a star
+falls, a soul was going up to God.
+
+ She again rubbed a match on the wall, and the light shone round
+her; in the brightness stood her old grandmother, clear and shining,
+yet mild and loving in her appearance. "Grandmother," cried the little
+one, "O take me with you; I know you will go away when the match burns
+out; you will vanish like the warm stove, the roast goose, and the
+large, glorious Christmas-tree." And she made haste to light the whole
+bundle of matches, for she wished to keep her grandmother there. And
+the matches glowed with a light that was brighter than the noon-day,
+and her grandmother had never appeared so large or so beautiful. She
+took the little girl in her arms, and they both flew upwards in
+brightness and joy far above the earth, where there was neither cold
+nor hunger nor pain, for they were with God.
+}
+
+\pdfannot % generic annotation
+ %
+ width 10cm % the dimension of the annotation can be controlled
+ height 0cm % via <rule spec>; if some of dimensions in
+ depth 4cm % <rule spec> is not given, the corresponding
+ % value of the parent box will be used.
+{ %
+ /Subtype /Text % text annotation
+ % /Open true % if given then the text annotation will be opened
+ % by default
+ /Contents % text contents
+ (This text is from THE LITTLE MATCH-SELLER by Hans Christian
+ Andersen)
+}
+
+\def\colsep{\qquad} % column separator
+\setbox0=\vbox{%
+ \baselineskip=1.2em plus 1pt minus 1pt
+ \hsize=2in
+ \tolerance=1000
+ \rightskip=0pt plus 1em
+ \hfuzz=1em
+ \parskip=\baselineskip
+ \null % will use \vsplit to remove this null box and
+ % insert \splittopskip glue to top of the
+ % first column. I don't know how to make the
+ % first column have the same height as other
+ % columns so have to use this trick to ensure
+ % that all columns will have \splittopskip glue
+ % properly inserted at the top
+ \text
+ \vfil}
+
+\setbox1=\vsplit0 to 0pt % remove the null box and insert \splittopskip glue
+\setbox3=\copy0 % make a copy of box0 for later use
+
+% Using thread by explicit determination which boxes will belong to a thread
+
+\setbox2=\hbox{}
+\loop
+ \setbox1=\vsplit0 to .75\vsize
+ \setbox2=\hbox{\unhbox2 \vtop{%
+ \pdfthread % add a bead to the thread with id=`num 1' (given
+ % below)
+ % <rule spec> % dimensions of the bead can be controlled
+ % via <rule spec>; if some of dimensions in
+ % <rule spec> is not given, the corresponding
+ % value of the parent box will be used. If
+ % \pdfthreadmargin is not zero then its value
+ % will be added to the margins of the bead
+ %
+ % additional attributes of thread
+ attr {/I <</Title (THE LITTLE MATCH-SELLER by Hans Christian)>>}
+ %
+ % identifier specification (exactly one of the
+ % following must be specified):
+ %
+ num 1 % num identifier (must be positive), or
+ % name {thread1} % name identifier; \pdfthread with the same id
+ % will be joined together. Attributes of the
+ % final thread is the last one if any was
+ % given.
+ \unvbox1}\colsep}
+\ifdim \ht0 > 0pt \repeat
+\box2
+
+\newpage
+
+% Using thread by automatic determination which boxes will belong to a
+% thread; \pdfstartthread has the same syntax as \pdfthread, apart that it
+% must be followed by a \pdfendthread. \pdfstartthread and the
+% corresponding \pdfendthread must end up in vboxes with the same
+% nesting level; all vboxes between them with the same nesting level will
+% be added into the thread. Note that during output routine if there are
+% other newly created boxes which have the same nesting level as vboxes
+% containing \pdfstartthread and \pdfendthread, they will be also added
+% into the thread, which is probably not what we want. To avoid such
+% unconsidered behaviour, it's often enough to wrap the box that shouldn't
+% belong to the thread by another box to change the nesting level.
+
+\setbox0=\vbox{%
+ \pdfstartthread
+ attr {/I <</Title (THE LITTLE MATCH-SELLER by Hans Christian)>>}%
+ name {thread2}%
+ \unvbox3
+ \pdfendthread
+}
+\setbox2=\hbox{}
+\loop
+ \setbox1=\vsplit0 to .75\vsize
+ \setbox2=\hbox{\unhbox2 \vtop{\unvbox1}\colsep}
+\ifdim \ht0 > 0pt \repeat
+\box2
+
+\newpage
+
+\pdfdest % destination for link and outlines
+ %
+ % identifier specification (exactly one of the
+ % following must be specified):
+ %
+ num 1 % num identifier (must be positive), or
+ % name {dest1} % name identifier. Must be unique in one document
+ %
+ % appearance of destination (exactly one of the
+ % following must be specified):
+ %
+ fit % fit whole page in window
+ % fith % fit whole width of page
+ % fitv % fit whole height of page
+ % fitb % fit whole "Bounding Box" page
+ % fitbh % fit whole width of "Bounding Box" of page
+ % fitbv % fit whole height of "Bounding Box" of page
+ % fitr <rule spec> % fit the rectangle specified by <rule spec>; if
+ % some of dimensions in <rule spec> is not given,
+ % the corresponding value of the parent box will be
+ % used. If \pdfdestmargin is not zero then its
+ % value will be added to the margins of the
+ % rectangle
+ % xyz % goto the current position
+
+This is a page containing destination `num 1'
+
+\newpage
+
+% \pdfstartlink and \pdfendlink are similar to \pdfstartthread and
+% \pdfendthread, but they must end up in hboxes instead of vboxes
+
+\leftline{This is a link to destination
+\pdfstartlink % start a link
+ %
+ height 10pt % dimensions of the link can be controlled
+ depth 3pt % via <rule spec>; if some of dimensions in
+ % <rule spec> is not given, the corresponding
+ % value of the parent box will be used. If
+ % \pdflinkmargin is not zero then its value
+ % will be added to the margins of the link
+ %
+ attr{/C [0.9 0 0] % additional attributes of link
+ /Border [0 0 2]} %
+ %
+ % action specification (exactly one of the
+ % following must be specified):
+ %
+ goto % goto action
+ %
+ % file{file.pdf} % optional file specification; can be used only with
+ % `goto' action or `thread' action (see below). If
+ % action identifier is name then there should be a
+ % destination or a thread with same name identifier
+ % in the file; if action identifier is number then it
+ % means page number for `goto' action (in this case it
+ % will take effect as `fitb' specification) and index
+ % number of thread for `thread' action (the first
+ % thread in a document has index number 0)
+ %
+ % goto action identifier (exactly one of the following
+ % must be specified):
+ %
+ num 1 % goto destination with num identifier
+ % name{dest1} % goto destination with name identifier
+ % page 1 {/Fit} % goto page 1 and fit the whole page
+ %
+ %
+ % thread % thread action; start to read a thread
+ %
+ %file{file.pdf} % optional file specification
+ %
+ % thread action type (exactly one of the following
+ % must be specified):
+ %
+ % num 1 % read thread with num identifier id=`num 1'
+ % name{thread2} % read thread with name identifier id=`name{thread2}'
+ %
+ %
+ % user{ % user-defined action; a URI action can be specified
+ % % as below
+ % /Subtype /Link
+ % /A <<
+ % /Type /Action
+ % /S /URI
+ % /URI (http://www.tug.org/)
+ % >>}
+`num 1'%
+\pdfendlink % end of link; if \pdfstartlink and
+ % \pdfendlink end up in different hboxes (in this
+ % case the boxes must have the same box nesting
+ % level), all hboxes between them will be treated
+ % as part of the link. Line breaks and even page
+ % breaks are allowed between \pdfstartlink and
+ % \pdfendlink
+}
+
+% more link examples
+
+\leftline{%
+ This is a link to the
+ \pdfstartlink
+ goto
+ page 1 {/FitB}% % goto the 1st page and fit the page BBox in the
+ % window
+ first page%
+ \pdfendlink}
+
+\leftline{%
+ This is a link to the
+ \pdfstartlink
+ thread num 1 % read the thread `num 1'
+ thread `num 1'%
+ \pdfendlink}
+
+\leftline{%
+ This is a link to
+ \pdfstartlink
+ attr{ /Border [0 0 0]} % make the bbox of the link invisible
+ user {% % a named action (undocumented in PDF spec)
+ /Subtype /Link
+ /A <<
+ /S /Named
+ /N /GoBack
+ >>}%
+ \Cyan the previous view\Black % color text inside the link
+ \pdfendlink}
+
+\leftline{%
+ This is a link to
+ \pdfstartlink user{%
+ /Subtype /Link
+ /A <<
+ /Type /Action
+ /S /URI
+ /URI (http://www.fi.muni.cz/)
+ >>}%
+ \Red our faculty\Black
+ \pdfendlink}
+
+{\hsize2in \raggedright \noindent
+ This is an example of
+ \pdfstartlink
+ attr{ /Border [0 0 0]} % make the bbox of the link invisible
+ goto page 1 {/FitB}%
+ \Red multiple line link. Make sure that the link and
+ its end must be in horizontal mode and the parent boxes must have the
+ same box nesting level.\Black
+ \pdfendlink
+ A common mistake here is using \primitive{pdfstartlink} at the
+ beginning of the text without \primitive{indent}, \primitive{noindent}
+ or \primitive{leavevmode}, so \primitive{pdfstartlink}
+ will end up in vertical mode and cause an error.
+ \par}
+
+% A sound or movie annotation can be created as below. Using such kinds of
+% annotation or Java script causes the pdf output to be system-dependent.
+% More info about this topic can be found in PDF spec.
+
+% \leftline{%
+% \pdfannot width 4in height 0in depth 3in {%
+% /Subtype /Movie
+% /Movie << /F (MovieFile.mov) >>}
+% An example of movie annotation}
+
+% \leftline{%
+% \pdfannot width 0in height 0in depth 0in {%
+% /Subtype /Sound
+% /Sound << /F (SoundFile.wav) >>}
+% An example of sound annotation}
+
+% \leftline{%
+% \pdfannot width 0in height 0in depth 0in {%
+% /Subtype /Movie
+% /Movie << /F (SoundFile.wav) >>}
+% Sound can be also embedded using Movie annotation}
+
+% outlines (bookmarks):
+\pdfoutline % outline entry specification
+ %
+ goto num 1 % action specification. This is the same as the action
+ % specification of `\pdfstartlink'
+ %
+ count 3 % number of direct subentries of this entry, 0 if this
+ % entry has no subentries (in this case it may be
+ % omitted). If after `count' follows an negative number
+ % then all subentries will be closed and the absolute
+ % value of this number specifies the number of
+ % direct subentries (see the following entries)
+ %
+ {Outline 1} % text contents of outline entry
+
+ \pdfoutline goto num 1 count -2{Outline 1.1}
+ \pdfoutline goto num 1 {Outline 1.1.1}
+ \pdfoutline goto num 1 {Outline 1.1.2}
+ \pdfoutline goto num 1 {Outline 1.2}
+ \pdfoutline goto num 1 {Outline 1.3}
+\pdfoutline goto page 1 {/Fit} {Outline 2}
+
+\newpage
+
+% Transformations are done by changing transformation matrices. See PDF spec for
+% more details how to use it. Generally, a transformation matrix is given as six
+% real numbers followed by operator `cm'. Before doing any transformation we must
+% store current graphic state (by operator `q') and restore it (by operator `Q')
+% after transformation. `q' and `Q' operators acts more or less like `gsave' and
+% `grestore' in Postscript. See examples below. Make sure that *no spacing*
+% can be produced during transformation and afterwards we must adjust spacing `by
+% hand'.
+
+\font\f=cmb10 at 50pt
+\setbox0=\hbox{\f Rotated text}
+\setbox1=\hbox{\f Scaled text}
+\setbox2=\hbox{\f Skewed text}
+
+\newdimen\d
+\newbox\tmpbox
+\def\avoidboxdimen#1{%
+ \setbox\tmpbox=\hbox{\box#1}%
+ \wd\tmpbox=0pt
+ \ht\tmpbox=0pt
+ \dp\tmpbox=0pt
+ \box\tmpbox}
+
+\hrule
+
+% rotation by `t' degrees counterclockwise is specified as
+% `cos(t) sin(t) -sin(t) cos(t) 0 0'.
+\vskip\wd0
+\leftline{\hskip\ht0\hskip\dp0%
+\pdfliteral{q 0 1 -1 0 0 0 cm}%
+\avoidboxdimen 0
+\pdfliteral{Q}}
+
+\hrule
+
+% scaling is specified as `Sx 0 0 Sy 0 0'
+\d=\ht1 \advance\d by \dp1
+\vskip3\d
+\pdfliteral{q 2 0 0 3 0 0 cm}%
+\avoidboxdimen 1
+\pdfliteral{Q}%
+
+\hrule
+
+% skewing x-axis by `u' degrees and y-axis by `v' degrees is specified as
+% `1 tan(u) tan(v) 1 0 0'.
+\d=\ht2 \advance\d by \dp2
+\vskip\d
+\d=0.57735\wd2 %tan(30) = 0.57735
+\pdfliteral{q 1 -0.57735 0 1 0 0 cm}%
+\avoidboxdimen 2
+\pdfliteral{Q}
+\vskip\d
+
+% To have a smoothly readable PDF output one may use a newline character to
+% separate entries written directly do PDF code. No matter for the viewer.
+
+\def\n{^^J}
+
+% If the file is modified are released oftenly (as this one) it might be convenient to
+% keep trace of modification time. In pdfTeX 1.30.0 there is a
+% \pdfcreationdate that returns a date of the file being created.
+% Date is formated in PDF way.
+
+\ifversion 1.30.0 \else
+
+\count100=\time
+\divide\count100 by60
+\edef\pdfcreationdate{\ifnum\count100<10 0\fi\the\count100} % hours
+\multiply\count100 by-60
+\advance\count100 by\time
+\edef\pdfcreationdate{%
+ \pdfcreationdate
+ \ifnum\count100<10 0\fi\the\count100 00} % minutes (seconds zeroed)
+\edef\pdfcreationdate{%
+ D:\the\year
+ \ifnum\month<10 0\fi\the\month
+ \ifnum\day<10 0\fi\the\day
+ \pdfcreationdate} % time zone discarded
+
+\fi
+
+\pdfinfo{% % Info dictionary of PDF output;
+ % all keys are optional.
+ /Author (Han The Thanh)
+ \n/CreationDate (D:20001212000000) % (D:YYYYMMDDhhmmss)
+ % YYYY year
+ % MM month
+ % DD day
+ % hh hour
+ % mm minutes
+ % ss seconds
+ %
+ % default: the actual date
+ %
+ \n/ModDate (\pdfcreationdate) % ModDate is similar
+ \n/Creator (TeX) % default: "TeX"
+ \n/Producer (pdfTeX) % default: "pdfTeX" + pdftex version
+ \n/Title (samplepdf.pdf) %
+ \n/Subject (Example) %
+ \n/Keywords (PDF TeX) %
+}
+
+\pdfcatalog{ % Catalog dictionary of PDF output.
+ /PageMode /UseOutlines %
+ /URI (http://www.fi.muni.cz/) %
+% pdfscreen-like setting might look like:
+% /PageMode /none
+% /ViewerPreferences <<
+% /HideToolbar true
+% /HideMenubar true
+% /HideWindowUI true
+% /FitWindow true
+% /CenterWindow true
+% >>
+}
+openaction goto page 1 {/Fit} % the action to be activated when
+ % opening the document; this is the
+ % same as <action spec> for links
+ % and outlines
+\end
diff --git a/Master/texmf/doc/pdftex/manual/samplepdf/supp-mis.tex b/Master/texmf/doc/pdftex/manual/samplepdf/supp-mis.tex
new file mode 100644
index 00000000000..ab089a297e1
--- /dev/null
+++ b/Master/texmf/doc/pdftex/manual/samplepdf/supp-mis.tex
@@ -0,0 +1,695 @@
+%D \module
+%D [ file=supp-mis,
+%D version=2004.10.26, % 1997.01.04,
+%D title=\CONTEXT\ Support Macros,
+%D subtitle=Missing (For Generic Use),
+%D author=Hans Hagen,
+%D date=\currentdate,
+%D copyright={PRAGMA / Hans Hagen \& Ton Otten}]
+%C
+%C This module is part of the \CONTEXT\ macro||package and is
+%C therefore copyrighted by \PRAGMA. See mreadme.pdf for
+%C details.
+
+%D Some support modules are more or less independant. This
+%D module, which is not part of plain \CONTEXT, provides the
+%D missing macros and declarations of registers.
+
+\ifx \undefined \writestatus \else \expandafter \endinput \fi
+
+%D Because \LATEX\ has no safe package loading mechanism, we
+%D need to take care of possible interference.
+
+\def\StartLatexHack
+ {\edef\StopLatexHack
+ {\catcode`\noexpand/=\the\catcode`/
+ \catcode`\noexpand:=\the\catcode`:
+ \catcode`\noexpand;=\the\catcode`;
+ \catcode`\noexpand"=\the\catcode`"
+ \catcode`\noexpand<=\the\catcode`<
+ \catcode`\noexpand>=\the\catcode`>}%
+ \catcode`/=12 \catcode`:=12 \catcode`;=12
+ \catcode`"=12 \catcode`<=12 \catcode`>=12 }
+
+%D This hack is needed especially for \LATEX\ users who use
+%D the Babel package. The Germans have active \type {"}'s, the
+%D Poles have \type {/}, while the French have \type {:} and
+%D \type {;} defines as command (thanks to Daniel Flipo for
+%D pointing that out and testing). Potentially active \type
+%D {?}'s and \type {!}'s are less dangerous since they are
+%D handled by the \type {\protect} and \type {\unprotect}
+%D macros.
+
+\StartLatexHack
+
+%D \macros
+%D {ifnocontextobject}
+%D
+%D First we take care of redundant defining. The next set of
+%D macros are a bit complicated by the fact that Plain
+%D \TEX\ defines the \type{\new}||macros as being outer.
+%D Furthermore nested \type{\if}'s can get us into
+%D trouble.
+
+\def\definecontextobject
+ {\iftrue}
+
+\def\gobblecontextobject
+ {\setbox0\hbox
+ \bgroup
+ \long\def\gobblecontextobject##1\fi{\egroup}%
+ \expandafter\gobblecontextobject\string}
+
+\long\def\ifnocontextobject#1\do
+ {\ifx#1\undefined
+ \expandafter\definecontextobject
+ \else
+ %\writestatus{system}{beware of conflicting \string#1}%
+ \expandafter\gobblecontextobject
+ \fi}
+
+%D \macros
+%D {beginETEX,beginTEX}
+%D
+%D Outside \CONTEXT\ we will not be \ETEX||aware.
+
+\long\def\beginETEX #1\endETEX {}
+\long\def\beginOMEGA#1\endOMEGA{}
+
+\let\beginTEX\relax \let\endTEX\relax
+
+%D \macros
+%D {writestatus}
+%D
+%D We start each module with a message. Normally the output is
+%D formatted, but here we keep things simple.
+
+\ifnocontextobject \writestatus \do
+
+ \def\writestatus#1#2%
+ {\immediate\write16{#1 : #2}}
+
+\fi
+
+%D Let's see if it works.
+
+\writestatus{loading}{Context Support Macros / Miscellaneous (2004.10.26)}
+
+%D \macros
+%D {protect,unprotect}
+%D
+%D Next we present a poor mans alternative for \type{\protect}
+%D and \type{\unprotect}, two commands that enable us to use
+%D the characters \type{@}, \type{!} and \type{?} in macro
+%D names.
+
+\ifnocontextobject \protect \do
+
+ \let\protect\relax
+
+\fi
+
+\newcount\protectiondepth
+
+\ifnocontextobject \unprotect \do
+
+ \def\unprotect
+ {\advance\protectiondepth 1
+ \ifnum\protectiondepth=1
+ \let\normalprotect=\protect
+ \def\protect
+ {\ifnum\protectiondepth>0
+ \advance\protectiondepth -1
+ \ifnum\protectiondepth=0
+ \doprotect
+ \let\protect=\normalprotect
+ \fi
+ \fi}
+ \edef\doprotect
+ {\catcode`\noexpand @=\the\catcode`@\relax
+ \catcode`\noexpand !=\the\catcode`!\relax
+ \catcode`\noexpand ?=\the\catcode`?\relax}
+ \catcode`@=11
+ \catcode`!=11
+ \catcode`?=11
+ \fi}
+
+\fi
+
+%D We start using this one it at once.
+
+\unprotect
+
+%D \macros
+%D {scratch...,if...,next...}
+%D
+%D We need some scratch registers. Users are free to use them,
+%D but can never be sure of their value once another macro is
+%D called. We only allocate things when they are yet
+%D undefined. This way we can't mess up other macro packages,
+%D but of course previous definitions can mess up our modules.
+
+\ifnocontextobject \donetrue \do \newif\ifdone \fi
+
+% no time now, will do a better test later (based on dimendef)
+
+\def\!!stringa{plain} \ifx\!!stringa\fmtname \donetrue \else
+\def\!!stringa{babel-plain} \ifx\!!stringa\fmtname \donetrue \else
+ \donefalse \fi \fi
+
+\ifdone
+ % plain defines some 15 dimens, so we need to define a few
+ % dummies in order to get out of the scratch area
+ \newdimen\scratchdimen % 16
+ \newdimen\scratchdimen % 17
+ \newdimen\scratchdimen % 18
+ \newdimen\scratchdimen % 19
+ \newdimen\scratchdimen % 20
+ \newdimen\scratchdimen % 21
+\fi
+
+\ifnocontextobject \scratchcounter \do \newcount \scratchcounter \fi
+\ifnocontextobject \scratchtoks \do \newtoks \scratchtoks \fi
+\ifnocontextobject \scratchdimen \do \newdimen \scratchdimen \fi
+\ifnocontextobject \scratchskip \do \newskip \scratchskip \fi
+\ifnocontextobject \scratchmuskip \do \newmuskip \scratchmuskip \fi
+\ifnocontextobject \scratchbox \do \newbox \scratchbox \fi
+\ifnocontextobject \scratchread \do \newread \scratchread \fi
+\ifnocontextobject \scratchwrite \do \newwrite \scratchwrite \fi
+
+%D Watch out, in the past we ran into troubles with \type {\onepoint}
+%D (and others) mening something different in \LATEX\ then here. In
+%D such situations clashes are bound to happen. For this reason the
+%D assignments are no inside the test. We try to catch those situations
+%D but we cannot keep ahead of teh future.
+
+\ifnocontextobject \zeropoint \do \newdimen \zeropoint \zeropoint = 0pt \fi % else problems with dimen12
+\ifnocontextobject \onepoint \do \newdimen \onepoint \onepoint = 1pt \fi
+\ifnocontextobject \onebasepoint \do \newdimen \onebasepoint \onebasepoint = 1bp \fi
+\ifnocontextobject \zerocount \do \chardef \zerocount = 0 \fi
+\ifnocontextobject \plusone \do \chardef \plusone = 1 \fi
+\ifnocontextobject \minusone \do \newcount \minusone \minusone = -1 \fi
+\ifnocontextobject \thousandpoint \do \newdimen \thousandpoint \thousandpoint = 1000pt \fi
+\ifnocontextobject \onerealpoint \do \newdimen \onerealpoint \onerealpoint = 1pt \fi % latex has a funny \onepoint
+
+\ifnocontextobject \emptytoks \do \newtoks \emptytoks \fi
+\ifnocontextobject \nextbox \do \newbox \nextbox \fi
+\ifnocontextobject \nextdepth \do \newdimen \nextdepth \fi
+
+\ifnocontextobject \CONTEXTtrue \do \newif\ifCONTEXT \fi
+\ifnocontextobject \eightbitcharacterstrue \do \newif\ifeightbitcharacters \fi
+\ifnocontextobject \MPdrawingdonetrue \do \newif\ifMPdrawingdone \fi
+
+\ifnocontextobject \ifzeropt \do \let\ifzeropt\ifcase \fi
+
+%D \macros
+%D {@@...}
+%D
+%D We use symbolic name for \CATCODES. They can only be used
+%D when we are in unprotected state.
+
+\ifnocontextobject \@@escape \do \chardef\@@escape = 0 \fi
+\ifnocontextobject \@@begingroup \do \chardef\@@begingroup = 1 \fi
+\ifnocontextobject \@@endgroup \do \chardef\@@endgroup = 2 \fi
+\ifnocontextobject \@@endofline \do \chardef\@@endofline = 5 \fi
+\ifnocontextobject \@@ignore \do \chardef\@@ignore = 9 \fi
+\ifnocontextobject \@@space \do \chardef\@@space = 10 \fi
+\ifnocontextobject \@@letter \do \chardef\@@letter = 11 \fi
+\ifnocontextobject \@@other \do \chardef\@@other = 12 \fi
+\ifnocontextobject \@@active \do \chardef\@@active = 13 \fi
+\ifnocontextobject \@@comment \do \chardef\@@comment = 14 \fi
+
+\def\s!sp{sp}
+\def\s!pt{pt}
+\def\s!bp{bp}
+
+%D \macros
+%D {@EA,expanded,expandoneargafter,expandtwoargsafter}
+%D
+%D Also needed:
+
+\let\@EA=\expandafter \let\@@expanded\empty
+
+\def\expanded#1%
+ {\long\xdef\@@expanded{\noexpand#1}\@@expanded}
+
+\def\expandoneargafter#1#2%
+ {\@EA#1\@EA{#2}}
+
+\def\expandtwoargsafter#1#2#3%
+ {\@EA\@EA\@EA#1\@EA\@EA\@EA{\@EA#2\@EA}\@EA{#3}}
+
+\def\@EAEAEA{\@EA\@EA\@EA}
+
+%D \macros
+%D {everyline,EveryLine,EveryPar}
+%D
+%D In \CONTEXT\ we use \type{\everypar} for special purposes
+%D and provide \type{\EveryPar} as an alternative. The same
+%D goes for \type{\everyline} and \type{\EveryLine}.
+
+\ifnocontextobject \everyline \do \newtoks\everyline \fi
+\ifnocontextobject \EveryPar \do \let\EveryPar =\everypar \fi
+\ifnocontextobject \EveryLine \do \let\EveryLine=\everyline \fi
+
+%D \macros
+%D {globallet}
+
+\def\globallet{\global\let}
+
+%D \macros
+%D {!!...}
+%D
+%D We reserve ourselves some scratch strings (i.e. macros)
+%D and some more counters.
+
+\ifnocontextobject \!!stringa \do \def\!!stringa {} \fi
+\ifnocontextobject \!!stringb \do \def\!!stringb {} \fi
+\ifnocontextobject \!!stringc \do \def\!!stringc {} \fi
+\ifnocontextobject \!!stringd \do \def\!!stringd {} \fi
+
+\ifnocontextobject \!!counta \do \newcount\!!counta {} \fi
+\ifnocontextobject \!!countb \do \newcount\!!countb {} \fi
+
+%D \macros
+%D {!!...}
+%D
+%D The next set of definitions speed up processing a bit.
+%D Furthermore it saves memory.
+
+\ifnocontextobject \!!zeropoint \do \def\!!zeropoint {0pt} \fi
+\ifnocontextobject \!!zerocount \do \def\!!zerocount {0} \fi
+\ifnocontextobject \!!tenthousand \do \def\!!tenthousand {10000} \fi
+
+\ifnocontextobject \!!width \do \def\!!width {width} \fi
+\ifnocontextobject \!!height \do \def\!!height {height} \fi
+\ifnocontextobject \!!depth \do \def\!!depth {depth} \fi
+
+\ifnocontextobject \!!plus \do \def\!!plus {plus} \fi
+\ifnocontextobject \!!minus \do \def\!!minus {minus} \fi
+\ifnocontextobject \!!to \do \def\!!to {to} \fi
+
+%D \macros
+%D {smashbox}
+%D
+%D The system modules offer a range of smashing macros, of
+%D which we only copied \type{\smashbox}.
+
+\ifnocontextobject \smashbox \do
+
+ \def\smashbox#1%
+ {\wd#1\zeropoint
+ \ht#1\zeropoint
+ \dp#1\zeropoint}
+
+\fi
+
+%D \macros
+%D {dowithnextbox}
+%D
+%D Also without further comment, we introduce a macro that
+%D gets the next box and does something usefull with it.
+%D Because the \type{\afterassignment} is executed inside the
+%D box, we have to use a \type{\aftergroup} too.
+
+\ifnocontextobject \dowithnextbox \do
+
+ \def\dowithnextbox#1%
+ {\def\dodowithnextbox{#1}%
+ \afterassignment\dododowithnextbox
+ \setbox\nextbox}
+
+ \def\dododowithnextbox%
+ {\aftergroup\dodowithnextbox}
+
+\fi
+
+%D \macros
+%D {setvalue,setevalue,setxvalue,,setgvalue,
+%D getvalue,
+%D letvalue,letgvalue}
+%D
+%D The next two macros expand their argument to
+%D \type{\argument}. The first one is used to define macro's
+%D the second one executes them.
+
+\ifnocontextobject \setvalue \do
+
+ \def\setvalue #1{\expandafter\def\csname#1\endcsname}
+ \def\setevalue#1{\expandafter\edef\csname#1\endcsname}
+ \def\setgvalue#1{\expandafter\gdef\csname#1\endcsname}
+ \def\setxvalue#1{\expandafter\xdef\csname#1\endcsname}
+ \def\getvalue #1{\csname#1\endcsname}
+ \def\letvalue #1{\expandafter\let\csname#1\endcsname}
+ \def\letgvalue#1{\global\expandafter\let\csname#1\endcsname}
+\fi
+
+%D \macros
+%D {unexpanded}
+%D
+%D The next command can be used as prefixed for commands that
+%D need protection during tests and writing to files. This
+%D is a very \CONTEXT\ specific one.
+
+\ifnocontextobject \unexpanded \do
+
+ \let\unexpanded\relax
+
+\fi
+
+%D \macros
+%D {convertargument}
+%D
+%D The original one offers a bit more, like global assignment, the
+%D the next implementation is however a bit more byte saving.
+
+\ifnocontextobject \convertargument \do
+
+ \def\doconvertargument#1>{}
+
+ \long\def\convertargument#1\to#2%
+ {\long\def\convertedargument{#1}%
+ \edef#2{\expandafter\doconvertargument\meaning\convertedargument}}
+
+\fi
+
+%D \macros
+%D {forgetall}
+%D
+%D Sometimes we have to disable interference of whatever kind
+%D of skips and mechanisms. The next macro resets some.
+
+\ifnocontextobject \forgetall \do
+
+ \def\forgetall
+ {\parskip\zeropoint
+ \leftskip\zeropoint
+ \parindent\zeropoint
+ \everypar{}}
+
+\fi
+
+%D \macros
+%D {withoutpt,
+%D ScaledPointsToBigPoints,ScaledPointsToWholeBigPoints}
+%D
+%D \TEX\ lacks some real datastructure. We can however use
+%D \DIMENSIONS. This kind of trickery is needed when we want
+%D \TEX\ to communicate with the outside world (by means of
+%D \type{\specials}).
+
+\ifnocontextobject \withoutpt \do
+
+ {\catcode`\.=\@@other
+ \catcode`\p=\@@other
+ \catcode`\t=\@@other
+ \gdef\WITHOUTPT#1pt{#1}}
+
+ \def\withoutpt#1%
+ {\expandafter\WITHOUTPT#1}
+
+ \def\ScaledPointsToBigPoints#1#2%
+ {\scratchdimen=#1sp\relax
+ \scratchdimen=.996264\scratchdimen
+ \edef#2{\withoutpt{\the\scratchdimen}}}
+
+ \def\ScaledPointsToWholeBigPoints#1#2%
+ {\scratchdimen=#1sp
+ \scratchdimen=.996264\scratchdimen
+ \scratchcounter=\scratchdimen
+ \advance\scratchcounter by 32768
+ \divide\scratchcounter by 65536
+ \edef#2{\the\scratchcounter}}
+
+\fi
+
+%D \macros
+%D {doprocessfile}
+%D
+%D This macro takes three arguments: the file number, the
+%D filename and a macro that handles the content of a read
+%D line.
+
+\newif\iffileprocessed
+
+\ifnocontextobject \doprocessfile \do
+
+ \def\doprocessfile#1#2#3%
+ {\openin#1=#2\relax
+ \ifeof#1%
+ \fileprocessedfalse
+ \closein#1\relax
+ \else
+ \fileprocessedtrue
+ \gdef\dofinishfile%
+ {\closein#1\relax
+ \global\let\doprocessline\relax}%
+ \gdef\doprocessline%
+ {\ifeof#1%
+ \dofinishfile
+ \else
+ \global\read#1 to \fileline
+ #3\relax
+ \expandafter\doprocessline
+ \fi}%
+ \expandafter\doprocessline
+ \fi}
+
+\fi
+
+%D \macros
+%D {uncatcodespecials}
+%D
+%D This one is taken from the \TEX\ book. The \CONTEXT\
+%D alternative is a bit different, but we hope this one works
+%D here.
+
+\ifx\dospecials\undefined
+
+ \def\dospecials
+ {\do\ \do\\\do\{\do\}\do\$%
+ \do\#\do\^\do\_\do\&\do\%%
+ \do\~\do\^^A\do\^^K}
+
+\fi
+
+\ifnocontextobject \uncatcodespecials \do
+
+ \def\uncatcodespecials
+ {\def\do##1{\catcode`##1=12 }\dospecials
+ \catcode`\ =\@@space
+ \catcode`\^^L=\@@ignore
+ \catcode`\^^M=\@@endofline
+ \catcode`\^^?=\@@ignore}
+
+\fi
+
+\ifnocontextobject \setnaturalcatcodes \do
+
+\def\setnaturalcatcodes
+ {\catcode`\!=\@@other \catcode`\?=\@@other \catcode`\@=\@@other
+ \catcode`\#=\@@other \catcode`\&=\@@other \catcode`\|=\@@other
+ \catcode`\$=\@@other \catcode`\^=\@@other \catcode`\_=\@@other
+ \catcode`\*=\@@other \catcode`\/=\@@other
+ \catcode`\-=\@@other \catcode`+=\@@other
+ \catcode`\==\@@other \catcode`\<=\@@other \catcode`\>=\@@other
+ \catcode`\"=\@@other \catcode`\'=\@@other \catcode`\`=\@@other
+ \catcode`\:=\@@other \catcode`\;=\@@other
+ \catcode`\,=\@@other \catcode`\.=\@@other \catcode`\~=\@@other
+ \catcode`\(=\@@other \catcode`\)=\@@other
+ \catcode`\{=\@@other \catcode`\}=\@@other
+ \catcode`\\=\@@other \catcode`\%=\@@other }
+
+\fi
+
+%D \macros
+%D {doglobal}
+%D
+%D Some \CONTEXT\ low level macros can have a \type{\doglobal}
+%D prefix. Let's just forget about that here:
+
+\ifnocontextobject \doglobal \do \let\doglobal\relax \fi
+
+%D The next obscure one is needed in the generic verbatim
+%D environment. When we end up with more of these, it's time
+%D to load the module \type{syst-gen}.
+
+\ifnocontextobject \doifincsnameelse \do
+
+ \def\dodoifincsnameelse#1#2%
+ {\def\dododoifincsnameelse##1#1##2##3\war%
+ {\csname\if##2@iffalse\else iftrue\fi\endcsname}%
+ \expandafter\dododoifincsnameelse#2#1@@\war}
+
+ \long\def\doifincsnameelse#1#2#3#4%
+ {\edef\@@instring{#1}%
+ \expandafter\dodoifincsnameelse\expandafter{\@@instring}{#2}%
+ #3%
+ \else
+ #4%
+ \fi}
+
+\fi
+
+%D \macros
+%D {dostepwiserecurse, dorecurse, doloop, exitloop}
+%D
+%D The next loop macro is a real weak one, and does not offer
+%D the full \CONTEXT\ functionality, let alone nesting, but
+%D for simple purposes, its behaviour is acceptable.
+
+\newcount\recursecounter
+
+\def\dostepwiserecurse#1#2#3#4% very weak and rubishly version
+ {\ifnum#2<#1\relax\else\dodostepwiserecurse{#1}{#2}{#3}{#4}\fi}
+
+\def\dodostepwiserecurse#1#2#3#4% very weak and rubishly version
+ {\recursecounter=#1\relax
+ \loop
+ \edef\recurselevel{\the\recursecounter}%
+ #4\relax
+ \ifnum\recursecounter<#2\relax
+ \advance\recursecounter by #3\relax
+ \repeat}
+
+\def\dorecurse#1%
+ {\dostepwiserecurse{1}{#1}{1}}
+
+\def\doloop
+ {\dostepwiserecurse{1}{\maxdimen}{1}}
+
+\def\exitloop
+ {\recursecounter=\maxdimen}
+
+%D \macros
+%D {ifundefined,doifdefined,doifundefined,
+%D doifdefinedelse,doifundefinedelse}
+%D
+%D These alteratives are not robust but suitable for simple
+%D usage. The official ones are a bit faster.
+
+\ifnocontextobject \doifdefined \do
+
+ \def\ifundefined#1%
+ {\expandafter\ifx\csname#1\endcsname\relax}
+
+ \def\doifdefinedelse#1#2#3%
+ {\expandafter\ifx\csname#1\endcsname\relax#3\else#2\fi}
+
+ \def\doifundefinedelse#1#2#3%
+ {\expandafter\ifx\csname#1\endcsname\relax#2\else#3\fi}
+
+ \def\doifdefined#1#2%
+ {\expandafter\ifx\csname#1\endcsname\relax\else#2\fi}
+
+ \def\doifundefined#1#2%
+ {\expandafter\ifx\csname#1\endcsname\relax#2\fi}
+
+\fi
+
+%D \macros
+%D {doifinstringelse}
+%D
+%D It seems like we end up with more and more macros here.
+%D Sigh.
+
+\ifnocontextobject \doifinstringelse \do
+
+ \def\p!doifinstringelse#1#2%
+ {\def\pp!doifinstringelse##1#1##2##3\war%
+ {\csname if\if##2@fals\else tru\fi e\endcsname}%
+ \expanded{\pp!doifinstringelse#2#1@@\noexpand\war}}
+
+ \long\def\doifinstringelse#1#2#3#4%
+ {\edef\@@@instring{#1}%
+ \@EA\p!doifinstringelse\@EA{\@@@instring}{#2}#3\else#4\fi}
+
+\fi
+
+%D \macros
+%D {twodigitrounding}
+%D
+%D We don't support rounding outside \CONTEXT. Sorry.
+
+\def\twodigitrounding#1{#1}
+
+%D \macros
+%D {lineheight}
+%D
+%D In \CONTEXT\ we have \type{\lineheight}, which in many
+%D cases matches \type {\baselineskip}.
+
+\ifnocontextobject \lineheight \do
+
+ \def\lineheight{\baselineskip}
+
+\fi
+
+%D \macros
+%D {dohandletokens}
+%D
+%D The following macro is the simplified version, but good
+%D enough for day to day hacks.
+%D
+%D \starttyping
+%D \dohandletokens some text\with\somemacro
+%D \stoptyping
+
+\ifnocontextobject \dohandletokens \do
+
+\def\dodohandletokens
+ {\ifx\next\end \else
+ \docommando{\next}%
+ \expandafter\dohandletokens
+ \fi}
+
+\def\dohandletokens
+ {\afterassignment\dodohandletokens\let\next= }
+
+\long\def\handletokens#1\with#2%
+ {\let\docommando=#2%
+ \dohandletokens#1\end}
+
+\fi
+
+%D Very reduced:
+
+\long\def\appendtoks#1\to#2%
+ {\scratchtoks{#1}\expanded{#2{\the#2\the\scratchtoks}}}
+
+%D Well, also handy.
+
+\def\doiffileelse#1#2#3%
+ {\immediate\openin\scratchread=#1\relax
+ \ifeof\scratchread
+ \def\next{#3}%
+ \else
+ \def\next{#2}%
+ \fi
+ \immediate\closein\scratchread
+ \next}
+
+%D New.
+
+\let\donothing\empty
+
+%D Also new:
+
+\def\letempty #1{\let#1\empty}
+\def\globalletempty#1{\global\let#1\empty}
+
+\def\letvalueempty #1{\expandafter\let\csname#1\endcsname\empty}
+\def\letgvalueempty#1{\global\expandafter\let\csname#1\endcsname\empty}
+
+%D Sigh
+
+\def\settrue #1{\chardef#1\zerocount}
+\def\setfalse#1{\chardef#1\plusone}
+
+\let\newconditional = \setfalse
+\let\ifconditional = \ifcase
+
+%D That's it. Please forget this junk and take a look at how
+%D it should be done.
+
+\StopLatexHack \protect \endinput
diff --git a/Master/texmf/doc/pdftex/manual/samplepdf/supp-pdf.tex b/Master/texmf/doc/pdftex/manual/samplepdf/supp-pdf.tex
new file mode 100644
index 00000000000..184cfb81582
--- /dev/null
+++ b/Master/texmf/doc/pdftex/manual/samplepdf/supp-pdf.tex
@@ -0,0 +1,2191 @@
+%D \module
+%D [ file=supp-pdf,
+%D version=2004.12.16,
+%D title=\CONTEXT\ Support Macros,
+%D subtitle=\METAPOST\ to \PDF\ conversion,
+%D author=Hans Hagen \& others (see text),
+%D date=\currentdate,
+%D copyright=\PRAGMA]
+%C
+%C This module is part of the \CONTEXT\ macro||package and is
+%C therefore copyrighted by \PRAGMA. See mreadme.pdf for
+%C details.
+
+%D These macros are written as generic as possible. Some
+%D general support macro's are loaded from a small module
+%D especially made for non \CONTEXT\ use. In this module I
+%D use a matrix transformation macro written by Tanmoy
+%D Bhattacharya. Thanks to extensive testing by Sebastian
+%D Ratz I was able to complete this module within reasonable
+%D time. This module has support for \METAPOST\ extensions
+%D built in.
+%D
+%D Daniel H. Luecking came up with a better (more precise)
+%D transformation method. You can recognize his comment by
+%D his initials. (We keep the old code around because it's a
+%D nice illustration on how a module like this evolves.)
+
+% Beware, we cannot use \zeropoint here since it may be
+% defined in the range \dimen 0 - 20 which we happen to use
+% as scratch registers; inside context we may consider
+% using dedicated registers.
+
+% fails: ( ) vect10 9.96265 fshow % \040\040\040\040
+%
+% some optimizations are possible, but we need to be generic
+
+%D First we take care of non||\CONTEXT\ use (newlines needed,
+%D expandafter not -).
+
+\ifx \undefined \writestatus \input supp-mis.tex \relax \fi
+
+\ifx \undefined \convertMPtoPDF \else \expandafter \endinput \fi
+
+\ifx \undefined \StartLatexHack \else \StartLatexHack \fi
+
+%D This module handles some \PDF\ conversion and insertions
+%D topics. By default, the macros use the \PDFTEX\ primitive
+%D \type{\pdfliteral} when available. Since \PDFTEX\ is now the
+%D default engine for \TEX\ distributions, we need a more complex
+%D test.
+
+\writestatus{loading}{Context Support Macros / PDF (2004.03.26)}
+
+\unprotect
+
+\ifx\PDFcode\undefined
+ \ifx\pdfliteral\undefined
+ \def\PDFcode#1{\special{PDF: #1}}
+ \else\ifx\pdfoutput\undefined
+ \def\PDFcode#1{\special{PDF: #1}}
+ \else\ifcase\pdfoutput
+ \def\PDFcode#1{\special{PDF: #1}}
+ \else % pdftex as well as in pdf mode
+ \let\PDFcode\pdfliteral
+ \fi\fi\fi
+\else
+ % we probably use context
+\fi
+
+%D First we define a handy constant:
+
+\bgroup \catcode`\%=\@@other \xdef\letterpercent{\string%} \egroup
+
+%D \macros
+%D {pdfimage,pdfimages,pdfclippedimage}
+%D
+%D Starting with pdftex version 14, images are included more
+%D natural to the form embedding. This enables alternative
+%D images to be embedded.
+%D
+%D \starttyping
+%D \pdfimage <optional dimensions> {file}
+%D \pdfimages <optional dimensions> {high res file} {low res file}
+%D \stoptyping
+%D
+%D The first one replaces the pre||version||14 original,
+%D while the latter provides alternative images.
+%D
+%D The next macro is dedicated to Maarten Gelderman, who
+%D needed to paste prepared \PDF\ pages into conference
+%D proceedings.
+%D
+%D \starttyping
+%D \pdfclippedimage <optional dimensions> {file} {l} {r} {t} {b}
+%D \stoptyping
+
+% \ifx\pdftexversion\undefined % no \m!systems for the sake of latex
+% \writestatus{systems}{Why not use pdf(e)TeX binaries?}
+% \protect
+% \expandafter\endinput
+% \fi
+
+\ifx\pdftexversion\undefined \else \ifnum\pdftexversion>13
+
+ \def\pdfimage#1#%
+ {\dopdfimage{#1}}
+
+ \def\dopdfimage#1#2%
+ {\immediate\pdfximage#1{#2}%
+ \pdfrefximage\pdflastximage}
+
+ \def\pdfimages#1#%
+ {\dopdfimages{#1}}
+
+ \def\dopdfimages#1#2#3%
+ {\immediate\pdfximage#1{#2}%
+ \immediate\pdfobj
+ {[ << /Image \the\pdflastximage\space0 R
+ /DefaultForPrinting true >> ]}%
+ \immediate\pdfximage#1
+ attr {/Alternates \the\pdflastobj\space0 R}{#3}%
+ \pdfrefximage\pdflastximage}
+
+ \def\pdfclippedimage#1#% specs {file}{left}{right}{top}{bottom}
+ {\dopdfclippedimage{#1}}
+
+ \def\dopdfclippedimage#1#2#3#4#5#6%
+ {\bgroup
+ \pdfximage#1{#2}%
+ \setbox\scratchbox\hbox
+ {\pdfrefximage\pdflastximage}%
+ \hsize\wd\scratchbox
+ \advance\hsize -#3
+ \advance\hsize -#4
+ \vsize\ht\scratchbox
+ \advance\vsize -#5
+ \advance\vsize -#6
+ \setbox\scratchbox\vbox to \vsize
+ {\vskip-#5\hbox to \hsize{\hskip-#3\box\scratchbox\hss}}%
+ \pdfxform\scratchbox
+ \pdfrefxform\pdflastxform
+ \egroup}
+
+\fi \fi
+
+%D If you want to save a few hash entries, you may prefer the
+%D less readable alternatives, like:
+%D
+%D \starttyping
+%D \def\pdfimage#1#% This one is less readable but needs no additional
+%D {\bgroup % hash entry for the second stage macro.
+%D \def\pdfimage##1%
+%D {\immediate\pdfximage##1{#2}%
+%D \pdfrefximage\pdflastximage\egroup}}
+%D \stoptyping
+
+%D For old times sake we provide a few aliases. These will be
+%D removed some day.
+
+\ifx\pdftexversion\undefined \else \ifnum\pdftexversion>13
+
+ \let\pdfform =\pdfxform
+ \let\pdflastform=\pdflastxform
+ \let\pdfrefform =\pdfrefxform
+
+\fi \fi
+
+%D \macros
+%D {convertPDFtoPDF}
+%D
+%D \PDFTEX\ supports verbatim inclusion of \PDF\ code. The
+%D following macro takes care of inserting externally defined
+%D illustrations in \PDF\ format. According to a suggestion
+%D Tanmoy Bhattacharya posted to the \PDFTEX\ mailing list, we
+%D first skip lines until \type{stream} is reached and then
+%D copy lines until \type{endstream} is encountered. This
+%D scheme only works with vectorized graphics in which no
+%D indirect references to objects are used. Bitmaps also don't
+%D work. Interpreting their specifications is beyond the
+%D current implementation.
+%D
+%D \starttyping
+%D \convertPDFtoPDF
+%D {filename}
+%D {x scale} {y scale}
+%D {x offset } {y offset}
+%D {width} {height}
+%D \stoptyping
+%D
+%D When the scales are set to~1, the last last four values
+%D are the same as the bounding box, e.g.
+%D
+%D \starttyping
+%D \convertPDFtoPDF{mp-pra-1.pdf} {1} {1}{-1bp}{-1bp}{398bp}{398bp}
+%D \convertPDFtoPDF{mp-pra-1.pdf}{.5}{.5} {0bp} {0bp}{199bp}{199bp}
+%D \stoptyping
+%D
+%D Keep in mind, that this kind of copying only works for
+%D pure and valid pdf code (without fonts).
+
+%D The scanning and copying is straightforward and quite fast.
+%D To speed up things we use two constants.
+
+\def\@@PDFstream@@ {stream}
+\def\@@PDFendstream@@ {endstream}
+
+%D \macros
+%D {PDFmediaboxprefered}
+%D
+%D If needed, the macros can scan for the mediabox that
+%D specifies the dimensions and offsets of the graphic. When
+%D we say:
+%D
+%D \starttyping
+%D \PDFmediaboxpreferedtrue
+%D \stoptyping
+%D
+%D the mediabox present in the file superseded the user
+%D specified, already scaled and calculated offset and
+%D dimensions. Beware: the user supplied values are not the
+%D bounding box ones!
+
+%D This code has become obsolete.
+
+% \newif\ifPDFmediaboxprefered
+
+\def\setPDFboundingbox#1#2#3#4#5#6%
+ {\dimen0=#1\dimen0=#5\dimen0
+ \ScaledPointsToBigPoints{\number\dimen0}\PDFxoffset
+ \dimen0=#3\dimen0=#5\dimen0
+ \xdef\PDFwidth{\the\dimen0}%
+ \dimen0=#2\dimen0=#6\dimen0
+ \ScaledPointsToBigPoints{\number\dimen0}\PDFyoffset
+ \dimen0=#4\dimen0=#6\dimen0
+ \xdef\PDFheight{\the\dimen0}%
+ \global\let\PDFxoffset\PDFxoffset
+ \global\let\PDFyoffset\PDFyoffset}
+
+\def\setPDFmediabox#1[#2 #3 #4 #5]#6\done
+ {\dimen2=#2bp\dimen2=-\dimen2 % \dimen2=-#2bp also works since tex handles --
+ \dimen4=#3bp\dimen4=-\dimen4 % \dimen4=-#3bp also works since tex handles --
+ \dimen6=#4bp\advance\dimen6 \dimen2
+ \dimen8=#5bp\advance\dimen8 \dimen4
+ \setPDFboundingbox{\dimen2}{\dimen4}{\dimen6}{\dimen8}\PDFxscale\PDFyscale}
+
+% \def\checkPDFmediabox#1/MediaBox#2#3\done
+% {\ifx#2\relax \else
+% \message{mediabox}%
+% \setPDFmediabox#2#3\done
+% \fi}
+
+%D We use the general macro \type{\doprocessfile} and feed this
+%D with a line handling macro that changes it's behavior when
+%D the stream operators are encountered.
+
+% \def\handlePDFline
+% {\ifx\@@PDFstream@@\fileline
+% \let\doprocessPDFline\copyPDFobject
+% \startPDFtoPDF
+% \else\ifPDFmediaboxprefered
+% \expandafter\checkPDFmediabox\fileline/MediaBox\relax\done
+% \fi\fi}
+
+% \def\copyPDFobject
+% {\ifx\@@PDFendstream@@\fileline
+% \ifPDFmediaboxprefered
+% \let\doprocessPDFline\findPDFmediabox
+% \else
+% \let\doprocessPDFline\relax
+% \fi
+% \else
+% \advance\scratchcounter 1
+% \PDFcode{\fileline}%
+% \fi}
+
+% \def\findPDFmediabox
+% {\expandafter\checkPDFmediabox\fileline/MediaBox\relax\done}
+
+%D The main conversion macro wraps the \PDF\ codes in a box
+%D that is output as an object. The graphics are embedded
+%D in~\type{q} and~\type{Q} and are scaled and positioned using
+%D one transform call (\type{cm}). This saves some additional
+%D scaling.
+
+%D \starttyping
+%D \def\startPDFtoPDF%
+%D {\setbox0=\vbox\bgroup
+%D \message{[PDF to PDF \PDFfilename}%
+%D \forgetall
+%D \scratchcounter=0
+%D \let\stopPDFtoPDF=\dostopPDFtoPDF}
+%D
+%D \def\dostopPDFtoPDF%
+%D {\ifnum\scratchcounter<0 \scratchcounter=1 \fi
+%D \message{(\the\scratchcounter\space lines)]}%
+%D \egroup
+%D \wd0=\PDFwidth
+%D \vbox to \PDFheight
+%D {\forgetall
+%D \vfill
+%D \PDFcode{q}%
+%D \PDFcode{1 0 0 1 \PDFxoffset\space \PDFyoffset\space cm}%
+%D \PDFcode{\PDFxscale\space 0 0 \PDFyscale\space 0 0 cm}%
+%D \box0
+%D \PDFcode{Q}}}
+%D
+%D \def\stopPDFtoPDF%
+%D {\message{[PDF to PDF \PDFfilename\space not found]}}
+%D
+%D \def\convertPDFtoPDF#1#2#3#4#5#6#7%
+%D {\bgroup
+%D \def\PDFfilename{#1}%
+%D \def\PDFxscale {#2}%
+%D \def\PDFyscale {#3}%
+%D \setPDFboundingbox{#4}{#5}{#6}{#7}{1}{1}%
+%D \uncatcodespecials
+%D \endlinechar=-1
+%D \let\doprocessPDFline=\handlePDFline
+%D \doprocessfile\scratchread\PDFfilename\doprocessPDFline
+%D \stopPDFtoPDF
+%D \egroup}
+
+\def\convertPDFtoPDF#1#2#3#4#5#6#7%
+ {\message{[PDF to PDF use \string\PDFcode instead]}%
+ \vbox{use the direct method instead}}
+
+%D \macros
+%D {dogetPDFmediabox}
+%D
+%D The next macro can be used to find the mediabox of a \PDF\
+%D illustration.
+%D
+%D \starttyping
+%D \dogetPDFmediabox
+%D {filename}
+%D {new dimen}{new dimen}{new dimen}{new dimen}
+%D \stoptyping
+%D
+%D Beware of dimen clashes: this macro uses the 5~default
+%D scratch registers! When no file or mediabox is found, the
+%D dimensions are zeroed.
+
+\def\dogetPDFmediabox#1#2#3#4#5%
+ {\bgroup
+ \def\PDFxscale{1}%
+ \def\PDFyscale{1}%
+ \uncatcodespecials
+ \endlinechar\minusone
+ \def\checkPDFtypepage##1/Type /Page##2##3\done%
+ {\ifx##2\relax
+ \else\if##2s% accept /Page and /Pages
+ \let\doprocessPDFline\findPDFmediabox
+ \else
+ \let\doprocessPDFline\findPDFmediabox
+ \fi\fi}%
+ \def\findPDFtypepage
+ {\expandafter\checkPDFtypepage\fileline/Type /Page\relax\done}%
+ \def\checkPDFmediabox##1/MediaBox##2##3\done%
+ {\ifx##2\relax \else
+ \setPDFmediabox##2##3\done
+ \fileprocessedtrue
+ \fi}%
+ \def\findPDFmediabox
+ {\expandafter\checkPDFmediabox\fileline/MediaBox\relax\done}%
+ \let\doprocessPDFline\findPDFtypepage
+ \doprocessfile\scratchread{#1}\doprocessPDFline
+ \egroup
+ \ifx\PDFxoffset\undefined
+ #2\zeropoint
+ #3\zeropoint
+ #4\zeropoint
+ #5\zeropoint
+ \else
+ #2=\PDFxoffset\onebasepoint
+ #3=\PDFyoffset\onebasepoint
+ #4=\PDFwidth
+ #5=\PDFheight
+ \fi}
+
+%D \macros
+%D {convertMPtoPDF}
+%D
+%D The next set of macros implements \METAPOST\ to \PDF\
+%D conversion. Because we want to test as fast as possible, we
+%D first define the \POSTSCRIPT\ operators that \METAPOST\
+%D uses. We don't define irrelevant ones, because these are
+%D skipped anyway.
+
+%D The converter can be made a bit faster by replacing the
+%D two test macros (the ones with the many \type {\if's}) by
+%D a call to named branch macros (something \typ {\getvalue
+%D {xPSmoveto}}. For everyday documents with relatively
+%D small graphics the gain in speed can be neglected.
+
+\def \PScurveto {curveto}
+\def \PSlineto {lineto}
+\def \PSmoveto {moveto}
+\def \PSshowpage {showpage}
+\def \PSnewpath {newpath}
+\def \PSfshow {fshow}
+\def \PSclosepath {closepath}
+\def \PSfill {fill}
+\def \PSstroke {stroke}
+\def \PSclip {clip}
+\def \PSrlineto {rlineto}
+\def \PSsetlinejoin {setlinejoin}
+\def \PSsetlinecap {setlinecap}
+\def \PSsetmiterlimit {setmiterlimit}
+\def \PSsetgray {setgray}
+\def \PSsetrgbcolor {setrgbcolor}
+\def \PSsetcmykcolor {setcmykcolor}
+\def \PSsetdash {setdash}
+\def \PSgsave {gsave}
+\def \PSgrestore {grestore}
+\def \PStranslate {translate}
+\def \PSscale {scale}
+\def \PSconcat {concat}
+\def \PSdtransform {dtransform}
+\def \PSsetlinewidth {setlinewidth}
+\def \PSpop {pop}
+
+\def \PSnfont {nfont} % was needed for TUG98 proceedings
+\def \PSspecial {special} % extensions to MetaPost
+
+%D A previous version set \type {%} to ignore, which
+%D simplified the following definitions. At the start of
+%D conversion the percent character was made active again.
+%D Because the whole graphic is one paragraph (there are no
+%D empty lines) this does not give the desired effect. This
+%D went unnoticed untill Scott Pakin sent me a test file
+%D percent characters in a string. So, from now on we have
+%D to prefix the following strings with percentages.
+
+\edef \PSBoundingBox {\letterpercent\letterpercent BoundingBox:}
+\edef \PSHiResBoundingBox {\letterpercent\letterpercent HiResBoundingBox:}
+\edef \PSExactBoundingBox {\letterpercent\letterpercent ExactBoundingBox:}
+\edef \PSMetaPostSpecial {\letterpercent\letterpercent MetaPostSpecial:}
+\edef \PSMetaPostSpecials {\letterpercent\letterpercent MetaPostSpecials:}
+\edef \PSPage {\letterpercent\letterpercent Page:}
+
+%D By the way, the \type {setcmykcolor} operator is not
+%D output by \METAPOST\ but can result from converting the
+%D \cap{RGB} color specifications, as implemented in
+%D \type{supp-mps}.
+
+%D In \POSTSCRIPT\ arguments precede the operators. Due to the
+%D fact that in some translations we need access to those
+%D arguments, and also because sometimes we have to skip them,
+%D we stack them up. The stack is one||dimensional for non path
+%D operators and two||dimensional for operators inside a path.
+%D This is because we have to save the whole path for
+%D (optional) postprocessing. Values are pushed onto the stack
+%D by:
+%D
+%D \starttyping
+%D \setMPargument {value}
+%D \stoptyping
+%D
+%D They can be retrieved by the short named macros:
+%D
+%D \starttyping
+%D \gMPa {number}
+%D \gMPs {number}
+%D \stoptyping
+%D
+%D When scanning a path specification, we also save the
+%D operator, using
+%D
+%D \starttyping
+%D \setMPkeyword {n}
+%D \stoptyping
+%D
+%D The path drawing operators are coded for speed: \type{clip},
+%D \type{stroke}, \type{fill} and \type{fillstroke} become
+%D 1, 2, 3 and~4.
+%D
+%D When processing the path this code can be retrieved
+%D using
+%D
+%D \starttyping
+%D \getMPkeyword % {n}
+%D \stoptyping
+%D
+%D When setting an argument, the exact position on the stack
+%D depends on the current value of the \COUNTERS\
+%D \type{\nofMPsegments} and \type{\nofMParguments}.
+
+\newcount\nofMPsegments
+\newcount\nofMParguments
+
+%D These variables hold the coordinates. The argument part of
+%D the stack is reset by:
+%D
+%D \starttyping
+%D \resetMPstack
+%D \stoptyping
+%D
+%D We use the prefix \type{@@MP} to keep the stack from
+%D conflicting with existing macros. To speed up things a bit
+%D more, we use the constant \type{\@@MP}.
+
+\def\@@MP{@@MP}
+
+\def\setMPargument% #1%
+ {\advance\nofMParguments \plusone
+ \expandafter\def
+ \csname\@@MP\the\nofMPsegments\the\nofMParguments\endcsname} % {#1}
+
+\def\letMPargument
+ {\advance\nofMParguments \plusone
+ \expandafter\let
+ \csname\@@MP\the\nofMPsegments\the\nofMParguments\endcsname}
+
+\def\setMPsequence#1 %
+ {\advance\nofMParguments \plusone
+ \expandafter\def
+ \csname\@@MP\the\nofMPsegments\the\nofMParguments\endcsname{#1}%
+ \handleMPsequence}
+
+\def\gMPa#1%
+ {\csname\@@MP0\number#1\endcsname}
+
+\def\gMPs#1%
+ {\csname\@@MP\the\nofMPsegments\number#1\endcsname}
+
+\def\dogMPa#1%
+ {\@EAEAEA\do\csname\@@MP0\number#1\endcsname}
+
+\def\setMPkeyword#1 %
+ {\expandafter\def\csname\@@MP\the\nofMPsegments0\endcsname{#1}%
+ \advance\nofMPsegments \plusone
+ \nofMParguments\zerocount}
+
+\def\getMPkeyword% #1%
+ {\csname\@@MP\the\nofMPsegments0\endcsname} % {\csname\@@MP#10\endcsname}
+
+%D When we reset the stack, we can assume that all further
+%D comment is to be ignored and handled in strings.
+%D By redefining the reset macro after the first call, we
+%D save some run time. Only use this macro after all
+%D comments are processed and use the simple alternative
+%D when dealing with comments.
+
+\def\doresetMPstack
+ {\nofMParguments\zerocount}
+
+\def\resetMPstack
+ {\let\handleMPgraphic\handleMPendgraphic
+ \let\resetMPstack\doresetMPstack
+ \resetMPstack}
+
+%D The arguments are saved with the preceding command
+%D \type{\do}. By default this command expands to nothing, but
+%D when we deal with strings it's used to strip off the
+%D \type{(} and \type{)}.
+%D
+%D Strings are kind of tricky, because characters can be
+%D passed verbatim \type{(hello)}, by octal number
+%D \type{(\005)} or as command \type{(\()}. We therefore
+%D cannot simply ignore \type{(} and \type{)}, the way we do
+%D with \type{[} and \type{]}. Another complication is that
+%D strings may contain characters that normally have a
+%D special meaning in \TEX, like \type{$} and \type{{}}.
+%D
+%D A previous solution made \type{\} an active character and
+%D let it look ahead for a number or characters. We had to
+%D abandon this scheme because of the need for verbatim
+%D support. The next solution involved some \CATCODE\
+%D trickery but works well.
+
+\def\octalMPcharacter#1#2#3%
+ {\char'#1#2#3\relax}
+
+\bgroup
+\catcode`\|=\@@comment
+\catcode`\%=\@@active
+\catcode`\[=\@@active
+\catcode`\]=\@@active
+\catcode`\{=\@@active
+\catcode`\}=\@@active
+\catcode`B=\@@begingroup
+\catcode`E=\@@endgroup
+\gdef\ignoreMPspecials|
+ B\let%\letterpercent|
+ \def[BE|
+ \def]BE|
+ \def{BE|
+ \def}BEE
+\gdef\obeyMPspecials|
+ B\def%B\char 37\relax E|
+ \def[B\char 91\relax E|
+ \def]B\char 93\relax E|
+ \def{B\char123\relax E|
+ \def}B\char125\relax EE
+\gdef\setMPspecials|
+ B\setnaturalcatcodes
+ \catcode`\\=\@@escape
+ \catcode`\%=\@@active
+ \catcode`\[=\@@active
+ \catcode`\]=\@@active
+ \catcode`\{=\@@active
+ \catcode`\}=\@@active
+ \lccode`\-=0 | latex sets this to `\-
+ \lccode`\%=`\% | otherwise it's seen as a number
+ \def\(B\char40\relax E|
+ \def\)B\char41\relax E|
+ \def\\B\char92\relax E|
+ \def\0B\octalMPcharacter0E|
+ \def\1B\octalMPcharacter1E|
+ \def\2B\octalMPcharacter2E|
+ \def\3B\octalMPcharacter3E|
+ \def\4B\octalMPcharacter4E|
+ \def\5B\octalMPcharacter5E|
+ \def\6B\octalMPcharacter6E|
+ \def\7B\octalMPcharacter7E|
+ \def\8B\octalMPcharacter8E|
+ \def\9B\octalMPcharacter9EE
+\egroup
+
+%D We use the comment symbol as a sort of trigger. Beware!
+%D The whole graphic is seen as on eparagraph, which means
+%D that we cannot change the catcodes in between.
+
+\bgroup
+\catcode`\%=\@@active
+\gdef\startMPscanning{\let%=\startMPconversion}
+\egroup
+
+%D In earlier versions we used the sequence
+%D
+%D \starttyping
+%D \expandafter\handleMPsequence\input filename\relax
+%D \stoptyping
+%D
+%D Persistent problems in \LATEX\ however forced us to use a
+%D different scheme. Every \POSTSCRIPT\ file starts with a
+%D \type{%}, so we temporary make this an active character
+%D that starts the scanning and redefines itself. (The problem
+%D originates in the redefinition by \LATEX\ of the
+%D \type{\input} primitive.)
+
+\def\startMPconversion
+ {\ignoreMPspecials
+ \handleMPsequence}
+
+%D Here comes the main loop. Most arguments are numbers. This
+%D means that they can be recognized by their \type{\lccode}.
+%D This method saves a lot of processing time. We could
+%D speed up the conversion by handling the \type{path}
+%D seperately.
+
+\def\@EAEAEA{\expandafter\expandafter\expandafter} % to be sure
+
+\def\dohandleMPsequence#1%
+ {\ifdone
+ \ifcase\lccode`#1\relax
+ \@EAEAEA\dohandleMPsequenceA
+ \else
+ \@EAEAEA\dohandleMPsequenceB
+ \fi
+ \else
+ \@EA\dohandleMPsequenceC
+ \fi#1}
+
+%\def\dohandleMPsequenceA#1 %
+% {\setMPargument{#1}%
+% \handleMPsequence}
+
+\let\dohandleMPsequenceA\setMPsequence
+
+\def\dohandleMPsequenceB#1 %
+ {\edef\somestring{#1}%
+ \ifx\somestring\PSmoveto
+ \edef\lastMPmoveX{\gMPa1}%
+ \edef\lastMPmoveY{\gMPa2}%
+ \PDFcode{\!MPgMPa1 \!MPgMPa2 m}%
+ \resetMPstack
+ \else\ifx\somestring\PSnewpath
+ \let\handleMPsequence\handleMPpath
+ \else\ifx\somestring\PSgsave
+ \PDFcode{q}%
+ \resetMPstack
+ \else\ifx\somestring\PSgrestore
+ \PDFcode{Q}%
+ \resetMPstack
+ \else\ifx\somestring\PSdtransform % == setlinewidth
+ \let\handleMPsequence\handleMPdtransform
+ % after that we will encounter more tokens until setlinewidth+pop
+ % or pop+setlinewidth which we catch next; we explicitly need to
+ % reset the stack since [] n setdash may follow; a more clever
+ % approach would be to read on till the condition is met, but it's
+ % the only pop / setlinewidth we will encounter so ...
+ \else\ifx\somestring\PSsetlinewidth
+ % already handled in dtransform
+ \resetMPstack
+ \else\ifx\somestring\PSpop
+ % already handled in dtransform
+ \resetMPstack
+ \else\ifx\somestring\PSconcat
+ \PDFcode{\gMPa1 \gMPa2 \gMPa3 \gMPa4 \gMPa5 \gMPa6 cm}%
+ \resetMPstack
+ \else\ifx\somestring\PSsetrgbcolor
+ \handleMPrgbcolor
+ \resetMPstack
+ \else\ifx\somestring\PSsetcmykcolor
+ \handleMPcmykcolor
+ \resetMPstack
+ \else\ifx\somestring\PSsetgray
+ \handleMPgraycolor
+ \resetMPstack
+ \else\ifx\somestring\PStranslate
+ \PDFcode{1 0 0 1 \gMPa1 \gMPa2 cm}%
+ \resetMPstack
+ \else\ifx\somestring\PSsetdash
+ \handleMPsetdash
+ \resetMPstack
+ \else\ifx\somestring\PSsetlinejoin
+ \PDFcode{\gMPa1 j}%
+ \resetMPstack
+ \else\ifx\somestring\PSsetmiterlimit
+ \PDFcode{\gMPa1 M}%
+ \resetMPstack
+ \else\ifx\somestring\PSfshow
+ \PDFcode{n}%
+ \handleMPfshow
+ \resetMPstack
+ \else\ifx\somestring\PSsetlinecap
+ \PDFcode{\gMPa1 J}%
+ \resetMPstack
+ \else\ifx\somestring\PSrlineto
+ \PDFcode{\!MP\lastMPmoveX\space\!MP\lastMPmoveY\space l S}%
+ \resetMPstack
+ \else\ifx\somestring\PSscale
+ \PDFcode{\gMPa1 0 0 \gMPa2 0 0 cm}%
+ \resetMPstack
+ \else\ifx\somestring\PSspecial
+ \handleMPspecialcommand
+ \resetMPstack
+ \else
+ \handleMPgraphic% {#1}%
+ \fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi
+ \handleMPsequence}
+
+\def\dohandleMPsequenceC#1 %
+ {\edef\somestring{#1}%
+ \handleMPgraphic % {#1}%
+ \handleMPsequence}
+
+%D Since colors are not sensitive to transformations, they
+%D are sometimes used for signaling. Therefore, we handle them
+%D separately. The next macro can be redefined if needed.
+
+\def\handleMPrgbcolor
+ {\PDFcode{\!MPgMPa1 \!MPgMPa2 \!MPgMPa3 rg
+ \!MPgMPa1 \!MPgMPa2 \!MPgMPa3 RG}}
+
+\def\handleMPcmykcolor
+ {\PDFcode{\!MPgMPa1 \!MPgMPa2 \!MPgMPa3 \!MPgMPa4 k
+ \!MPgMPa1 \!MPgMPa2 \!MPgMPa3 \!MPgMPa4 K}}
+
+\def\handleMPgraycolor
+ {\PDFcode{\!MPgMPa1 g
+ \!MPgMPa1 G}}
+
+\def\handleMPspotcolor
+ {\PDFcode{0 g
+ 0 G}}
+
+%D Beginning and ending the graphics is taken care of by the
+%D macro \type{\handleMPgraphic}, which is redefined when
+%D the first graphics operator is met.
+
+\def\handleMPendgraphic % #1%
+ {\ifx\somestring\PSshowpage
+ \let\handleMPsequence\finishMPgraphic
+ \else
+ \letMPargument\somestring % {#1}%
+ \fi}
+
+\def\handleMPbegingraphic % #1%
+ {\ifx\somestring\PSBoundingBox
+ \def\handleMPsequence{\handleMPboundingbox1}%
+ \else\ifx\somestring\PSHiResBoundingBox
+ \def\handleMPsequence{\handleMPboundingbox2}%
+ \else\ifx\somestring\PSExactBoundingBox
+ \def\handleMPsequence{\handleMPboundingbox3}%
+ \else\ifx\somestring\PSshowpage
+ \let\handleMPsequence\finishMPgraphic
+ \else\ifx\somestring\PSPage
+ \let\handleMPsequence\handleMPpage
+ \else\ifx\somestring\PSMetaPostSpecials
+ \let\handleMPsequence\handleMPspecialscomment
+ \else\ifx\somestring\PSMetaPostSpecial
+ \let\handleMPsequence\handleMPspecialcomment
+ \else
+ \letMPargument\somestring % {#1}%
+ \fi\fi\fi\fi\fi\fi\fi}
+
+\let\handleMPgraphic=\handleMPbegingraphic
+
+%D We check for three kind of bounding boxes: the normal one
+%D and two high precision ones:
+%D
+%D \starttyping
+%D BoundingBox: llx lly ucx ucy
+%D HiResBoundingBox: llx lly ucx ucy
+%D ExactBoundingBox: llx lly ucx ucy
+%D \stoptyping
+%D
+%D The original as well as the recalculated dimensions are
+%D saved for later use.
+
+\newif\ifskipemptyMPgraphic \skipemptyMPgraphicfalse
+
+\chardef\currentMPboundingbox=0
+
+\def\handleMPboundingbox#1#2 #3 #4 #5
+ {\ifnum#1>\currentMPboundingbox
+ \xdef\MPllx{#2}\xdef\MPlly{#3}%
+ \xdef\MPurx{#4}\xdef\MPury{#5}%
+ \dimen0=#2\onepoint
+ \dimen0=-\MPxscale\dimen0
+ \dimen2=#3\onepoint
+ \dimen2=-\MPyscale\dimen2
+ \xdef\MPxoffset{\withoutpt\the\dimen0}%
+ \xdef\MPyoffset{\withoutpt\the\dimen2}%
+ \dimen0=#2\onebasepoint
+ \dimen0=-\dimen0
+ \dimen2=#3\onebasepoint
+ \dimen2=-\dimen2
+ \advance\dimen0 #4\onebasepoint
+ \dimen0=\MPxscale\dimen0
+ \xdef\MPwidth{\the\dimen0}%
+ \advance\dimen2 #5\onebasepoint
+ \xdef\MPyshift{\the\dimen2}% unscaled
+ \dimen2=\MPyscale\dimen2
+ \xdef\MPheight{\the\dimen2}%
+ \chardef\currentMPboundingbox#1\relax
+ \fi
+ \doresetMPstack
+ \let\handleMPsequence\dohandleMPsequence
+ \let\next\handleMPsequence
+ \ifskipemptyMPgraphic
+ \ifdim\MPheight=\zeropoint\relax\ifdim\MPwidth=\zeropoint\relax
+ \def\next{\endinput\finishMPgraphic}%
+ \fi\fi
+ \fi
+ \next}
+
+%D Unless defined otherwise, we simply ignore specialcomments.
+
+\def\handleMPspecialcomment
+ {\doresetMPstack
+ \let\handleMPsequence\dohandleMPsequence
+ \handleMPsequence}
+
+\let\handleMPspecialscomment\handleMPspecialcomment
+
+%D We use the \type{page} comment as a signal that
+%D stackbuilding can be started.
+
+\def\handleMPpage #1 #2
+ {\doresetMPstack
+ \donetrue
+ \let\handleMPsequence\dohandleMPsequence
+ \handleMPsequence}
+
+%D The same applies to the special extensions.
+
+\def\handleMPspecialcommand
+ {\doresetMPstack
+ \let\handleMPsequence\dohandleMPsequence
+ \handleMPsequence}
+
+%D \METAPOST\ draws its dots by moving to a location and
+%D invoking \type{0 0 rlineto}. This operator is not
+%D available in \PDF. Our solution is straightforward: we draw
+%D a line from $(current\_x, current\_y)$ to itself. This
+%D means that the arguments of the preceding \type{moveto} have
+%D to be saved.
+
+\def\lastMPmoveX{0}
+\def\lastMPmoveY{0}
+
+%D These saved coordinates are also used when we handle the
+%D texts. Text handling proved to be a bit of a nuisance, but
+%D finally I saw the light. It proved that we also had to
+%D take care of \type{(split arguments)}.
+
+\def\setMPfshowfont#1#2%
+ {\font\temp=#1\space at #2\relax\temp}
+
+\let\MPfshowcommand\empty
+
+\def\dohandleMPfshow
+ {\bgroup
+ \setbox\scratchbox\hbox
+ {\obeyMPspecials
+ \edef\size{\gMPa\nofMParguments}%
+ \ifx\size\PSnfont % round font size (to pt)
+ \advance\nofMParguments \minusone
+ \expandafter\scratchdimen\gMPa\nofMParguments\onepoint\relax
+ \ifdim\scratchdimen<\onepoint
+ \def\size{1pt}%
+ \else
+ \advance\scratchdimen .5\onepoint
+ \def\size##1.##2\relax{\def\size{##1pt}}%
+ \expandafter\size\the\scratchdimen\relax
+ \fi
+ \else
+ \edef\size{\size bp}%
+ \fi
+ \advance\nofMParguments \minusone
+ %\font\temp=\gMPa\nofMParguments\space at \size
+ \let\temp\relax % to be sure
+ \setMPfshowfont{\gMPa\nofMParguments}\size
+ \advance\nofMParguments \minusone
+ \temp
+ \MPfshowcommand
+ {\ifnum\nofMParguments=\plusone
+ \def\do(##1){##1}%
+ \dogMPa1%
+ \else
+ % we need to catch ( a ) (a a a) (\123 \123 \123) etc
+ \scratchcounter\plusone
+ \def\dodo##1% Andreas Fieger's bug: (\304...)
+ {\edef\!!stringa{##1\empty\empty}% and another one: ( 11) -> \ifx 11
+ \ifx\!!stringa\MPspacechar\MPspacechar\else\expandafter##1\fi}%
+ \def\do(##1{\dodo{##1}}%
+ \dogMPa\scratchcounter\MPspacechar
+ \let\do\relax
+ \loop
+ \advance\scratchcounter \plusone
+ \ifnum\scratchcounter<\nofMParguments\relax
+ \gMPa\scratchcounter\MPspacechar
+ \repeat
+ \def\do##1){\dodo{##1}}%
+ \dogMPa\scratchcounter
+ \fi
+ \unskip}}%
+ %
+ % this fails in some versions of pdftex
+ %
+ % \dimen0=\lastMPmoveY bp
+ % \advance\dimen0 by \ht0
+ % \ScaledPointsToBigPoints{\number\dimen0}\lastMPmoveY
+ % \PDFcode{n q 1 0 0 1 \lastMPmoveX\space\lastMPmoveY\space cm}%
+ % \dimen0=\ht0
+ % \advance\dimen0 by \dp0
+ % \box0
+ % \vskip-\dimen0
+ % \PDFcode{Q}%
+ % \egroup}
+ %
+ \setbox\scratchbox\hbox
+ {\hskip\lastMPmoveX\onebasepoint\raise\lastMPmoveY\onebasepoint\box\scratchbox}%
+ \ht\scratchbox\zeropoint
+ \dp\scratchbox\zeropoint
+ \wd\scratchbox\zeropoint
+ \box\scratchbox
+ \egroup}
+
+\let\handleMPfshow\dohandleMPfshow % so we can overload this one later
+
+%D You could consider the following definition to be the most
+%D natural one.
+
+% \def\MPspacechar{\space} % normal case
+
+\def\MPspacechar{\char32\relax} % old solution does not work with math
+
+%D However, the following implementation is more robust, since
+%D some fonts have funny visible spaces in the space slot. This
+%D gives a mismatch between the space that \METAPOST\ took into
+%D account and the \quote {natural} space. This only happens in
+%D labels, since \type {btex}||\type {etex} thingies don't have
+%D spaces. This phenomena showed up when preparing the
+%D \METAFUN\ manual, where Palatino fonts are used. We can
+%D safely assume that \METAPOST\ considers \type {\char32} to
+%D be the space.
+
+\def\MPspacechar{\setbox\scratchbox\hbox{\char32}\kern\wd\scratchbox}
+
+%D Well, this does not work with math fonts, so:
+
+\def\MPspacechar{\char32\relax}
+
+%D Most operators are just converted and keep their
+%D arguments. Dashes however need a bit different treatment,
+%D otherwise \PDF\ viewers complain loudly. Another
+%D complication is that one argument comes after the \type{]}.
+%D When reading the data, we simply ignore the array boundary
+%D characters. We save ourselves some redundant newlines and
+%D at the same time keep the output readable by packing the
+%D literals.
+
+\def\handleMPsetdash
+ {\bgroup
+ \def\somestring{[}%
+ \scratchcounter\plusone
+ \loop
+ \ifnum\scratchcounter<\nofMParguments
+ \edef\somestring{\somestring\space\gMPa\scratchcounter}%
+ \advance\scratchcounter \plusone
+ \repeat
+ \edef\somestring{\somestring]\gMPa\scratchcounter\space d}%
+ \PDFcode{\somestring}%
+ \egroup}
+
+%D The \type{setlinewidth} commands looks a bit complicated. There are
+%D two alternatives, that result in a similar look in both
+%D $x$- and $y$-dorection. As John Hobby says:
+%D
+%D \startnarrower \switchtobodyfont[ss]
+%D \starttyping
+%D x 0 dtransform exch truncate exch idtransform pop setlinewidth
+%D 0 y dtransform truncate idtransform setlinewidth pop
+%D \stoptyping
+%D
+%D These are just fancy versions of \type{x setlinewidth} and
+%D \type{y setlinewidth}. The \type{x 0 ...} form is used if
+%D the path is {\em primarily vertical}. It rounds the width
+%D so that vertical lines come out an integer number of pixels
+%D wide in device space. The \type{0 y ...} form does the same
+%D for paths that are {\em primarily horizontal}. The reason
+%D why I did this is Knuth insists on getting exactly the
+%D widths \TEX\ intends for the horizontal and vertical rules
+%D in \type{btex...etex} output. (Note that PostScript scan
+%D conversion rules cause a horizontal or vertical line of
+%D integer width $n$ in device space to come out $n+1$ pixels
+%D wide, regardless of the phase relative to the pixel grid.)
+%D \stopnarrower
+%D
+%D The common operator in these sequences is \type{dtransform},
+%D so we can use this one to trigger setting the linewidth.
+
+\def\handleMPdtransform
+ {\ifdim\gMPa1\onepoint>\zeropoint
+ \PDFcode{\gMPa1 w}%
+ \def\next##1 ##2 ##3 ##4 ##5 ##6 {\handleMPsequence}%
+ \else
+ \PDFcode{\gMPa2 w}%
+ \def\next##1 ##2 ##3 ##4 {\handleMPsequence}%
+ \fi
+ \let\handleMPsequence\dohandleMPsequence
+ \resetMPstack
+ \next}
+
+%D The most complicated command is \type{concat}. \METAPOST\
+%D applies this operator to \type{stroke}. At that moment the
+%D points set by \type{curveto} and \type{moveto}, are already
+%D fixed. In \PDF\ however the \type{cm} operator affects the
+%D points as well as the pen (stroke). Like more \PDF\
+%D operators, \type{cm} is defined in a bit ambiguous way.
+%D The only save route for non||circular penshapes, is saving
+%D the path, recalculating the points and applying the
+%D transformation matrix in such a way that we can be sure
+%D that its behavior is well defined. This comes down to
+%D inverting the path and applying \type{cm} to that path as
+%D well as the pen. This all means that we have to save the
+%D path.
+
+%D In \METAPOST\ there are three ways to handle a path $p$:
+%D
+%D \starttyping
+%D draw p; fill p; filldraw p;
+%D \stoptyping
+%D
+%D The last case outputs a \type{gsave fill grestore} before
+%D \type{stroke}. Handling the path outside the main loops
+%D saves about 40\% run time.\footnoot{We can save some more by
+%D following the \METAPOST\ output routine, but for the moment
+%D we keep things simple.} Switching between the main loop and
+%D the path loop is done by means of the recursely called
+%D macro \type{\handleMPsequence}.
+
+\def\handleMPpath
+ {\chardef\finiMPpath0
+ \let\closeMPpath\relax
+ \let\flushMPpath\flushnormalMPpath
+ \resetMPstack
+ \nofMPsegments\plusone
+ \let\handleMPsequence\dohandleMPpath
+ \dohandleMPpath}
+
+%D Most paths are drawn with simple round pens. Therefore we've
+%D split up the routine in two.
+
+\def\flushnormalMPsegment
+ {\ifcase\getMPkeyword\relax
+ \PDFcode{\!MPgMPs1 \!MPgMPs2 l}%
+ \or
+ \PDFcode{\!MPgMPs1 \!MPgMPs2 \!MPgMPs3 \!MPgMPs4 \!MPgMPs5 \!MPgMPs6 c}%
+ \or
+ \PDFcode{\!MP\lastMPmoveX\space\!MP\lastMPmoveY\space l S}%
+ \or
+ \edef\lastMPmoveX{\gMPs1}% evt \!MP here
+ \edef\lastMPmoveY{\gMPs2}%
+ \PDFcode{\!MP\lastMPmoveX\space \!MP\lastMPmoveY\space m}%
+ \fi}
+
+\def\flushconcatMPsegment
+ {\ifcase\getMPkeyword\relax
+ \doMPconcat{\gMPs1}\a{\gMPs2}\b%
+ \PDFcode{\!MP\a\space\!MP\b\space l}%
+ \or
+ \doMPconcat{\gMPs1}\a{\gMPs2}\b%
+ \doMPconcat{\gMPs3}\c{\gMPs4}\d%
+ \doMPconcat{\gMPs5}\e{\gMPs6}\f%
+ \PDFcode{\!MP\a\space\!MP\b\space
+ \!MP\c\space\!MP\d\space
+ \!MP\e\space\!MP\f\space c}%
+ \or
+ \bgroup
+ \noMPtranslate
+ \doMPconcat\lastMPmoveX\a\lastMPmoveY\b%
+ \PDFcode{\!MP\a\space\!MP\b\space l S}%
+ \egroup
+ \or
+ \edef\lastMPmoveX{\gMPs1}%
+ \edef\lastMPmoveY{\gMPs2}%
+ \doMPconcat\lastMPmoveX\a\lastMPmoveY\b%
+ \PDFcode{\!MP\a\space\!MP\b\space m}%
+ \fi}
+
+% \def\flushnormalMPpath
+% {\scratchcounter\nofMPsegments
+% \nofMPsegments\plusone
+% \loop
+% \flushnormalMPsegment
+% \advance\nofMPsegments \plusone
+% \ifnum\nofMPsegments<\scratchcounter
+% \repeat}
+%
+% \def\flushconcatMPpath
+% {\scratchcounter\nofMPsegments
+% \nofMPsegments\plusone
+% \loop
+% \flushconcatMPsegment
+% \advance\nofMPsegments \plusone
+% \ifnum\nofMPsegments<\scratchcounter
+% \repeat}
+%
+% an alternative is presented below: (no \def assignment)
+
+\def\doflushsomeMPpath
+ {\dodoflushsomeMPpath
+ \advance\nofMPsegments \plusone
+ \ifnum\nofMPsegments<\scratchcounter
+ \expandafter\doflushsomeMPpath
+ \fi}
+
+\def\flushsomeMPpath
+ {\scratchcounter\nofMPsegments
+ \nofMPsegments\plusone
+ \doflushsomeMPpath}
+
+\def\flushnormalMPpath{\let\dodoflushsomeMPpath\flushnormalMPsegment\flushsomeMPpath}
+
+%OLD \def\flushconcatMPpath{\let\dodoflushsomeMPpath\flushconcatMPsegment\flushsomeMPpath}
+
+%NEW pre-calculate 1/D so it needn't be repeated for each control point.
+
+\def\flushconcatMPpath
+ {\MPreciprocaldeterminant
+ \let\dodoflushsomeMPpath\flushconcatMPsegment\flushsomeMPpath}
+
+%D The transformation of the coordinates is handled by one of
+%D the macros Tanmoy posted to the \PDFTEX\ mailing list.
+%D I rewrote and optimized the original macro to suit the other
+%D macros in this module.
+%D
+%D \starttyping
+%D \doMPconcat {x position} \xresult {y position} \yresult
+%D \stoptyping
+%D
+%D By setting the auxiliary \DIMENSIONS\ \type{\dimen0} upto
+%D \type{\dimen10} only once per path, we save over 20\% run
+%D time. Some more speed was gained by removing some parameter
+%D passing. These macros can be optimized a bit more by using
+%D more constants. There is however not much need for further
+%D optimization because penshapes usually are round and
+%D therefore need no transformation. Nevertheless we move the
+%D factor to the outer level and use a bit different \type{pt}
+%D removal macro. Although the values represent base points,
+%D we converted them to pure points, simply because those can
+%D be converted back.
+
+%OLD \mathchardef\MPconcatfactor=256 % beware don't remove spaces before it
+
+%OLD \def\doMPreducedimen#1
+%OLD {\count0\MPconcatfactor
+%OLD \advance\dimen#1 \ifdim\dimen#1>\zeropoint .5\else -.5\fi\count0
+%OLD \divide\dimen#1 \count0\relax}
+
+%OLD % too inaccurate (see old pragma logo)
+%OLD
+%OLD \def\doMPreducedimen#1
+%OLD {\count0=\MPconcatfactor
+%OLD \divide\dimen#1 \count0\relax}
+
+%OLD \def\doMPreducedimen#1
+%OLD {\advance\dimen#1 \ifdim\dimen#1>\zeropoint .5\else -.5\fi\MPconcatfactor
+%OLD \divide\dimen#1 \MPconcatfactor}
+
+%D The transformation code is rewritten by Daniel H. Luecking who
+%D describes his patch as follows:
+%D
+%D We would like to divide 1 by $X4, but all divisions are integer so
+%D for accuracy we want to convert to large integers and make sure the
+%D integer quotient has as many significant digits as possible. Thus we
+%D need to replace $1/X$ with $M/N$ where $N$ is as large as possible
+%D and $M/N$ is as large as possible. Also for simplicity $M$ should be
+%D a power of 2. So we make $M = 2^{30}$ \footnote{$2^{31} - 1$ is the
+%D largest legal integer. Using it (and simply ignoring the inaccuracy
+%D caused by $-1$) turns out to be at least as accurate in all cases,
+%D and more accurate in some.} (largest legal power of 2) and adjust
+%D $X4 downward (if necessary) to the the range $1-2^{16}$. This gives
+%D at least 15 significant binary digits, (almost as accurate as
+%D \METAPOST\ for numbers near 1) or almost 5 significant figures
+%D (decimal).
+
+\newcount\MPscratchCnt
+\newdimen\MPscratchDim % will be assigned global
+
+\def\MPadjustdimen % sets \MPscratchDim and \MPscratchCnt
+ {\MPscratchCnt\zerocount
+ \doMPadjustdimen}
+
+\def\doMPadjustdimen
+ {\ifdim\MPscratchDim>\onepoint
+ \divide\MPscratchDim 2
+ \advance\MPscratchCnt \plusone
+ \expandafter\doMPadjustdimen
+ \fi}
+
+%OLD \def\doMPexpanddimen#1
+%OLD {\multiply\dimen#1 \MPconcatfactor\relax}
+
+%D DHL: When viewed as an integer, $1 \hbox{pt}=2^{16}$ so $2^{32}/X$
+%D is the right way to do $(1 \hbox{pt})/(X \hbox{pt})$ and get the
+%D answer in points. But we are limited to $2^{30}/X$. However, we
+%D actually do $[ 2^{30} / (X/2^K) ]*2^{2-K}$ where $K$ is the number
+%D of halvings it takes to bring $X4 below $1 \hbox{pt}$. If $K$ is 0
+%D or 1 we readjust by multiplying by 4 or 2, otherwise by halving
+%D $(K-2)$ times \type {\MPscratchCnt} holds the value of $K$ from
+%D \type {\MPadjustdimen}.
+
+\def\MPreadjustdimen % acts on \MPscratchDim and MPscratchCnt
+ {\ifcase\MPscratchCnt
+ \multiply\MPscratchDim 4
+ \or
+ \multiply\MPscratchDim 2
+ \else
+ \expandafter\doMPreadjustdimen
+ \fi}
+
+\def\doMPreadjustdimen
+ {\ifnum\MPscratchCnt > 2
+ \divide\MPscratchDim 2
+ \advance\MPscratchCnt \minusone
+ \expandafter\doMPreadjustdimen
+ \fi}
+
+\def\MPreciprocaldeterminant
+ {\MPscratchDim\withoutpt\the\dimen0 \dimen6 % s_x*s_y
+ \advance\MPscratchDim - \withoutpt\the\dimen2 \dimen4 % s_x*s_y - r_x*r_y
+ \ifdim\MPscratchDim<\zeropoint % we need a positive dimension
+ \MPscratchDim-\MPscratchDim % for \MPadjustdimen
+ \doMPreciprocal
+ \MPscratchDim-\MPscratchDim
+ \else
+ \doMPreciprocal
+ \fi}
+
+\newcount\MPnumerator \MPnumerator = 1073741824 % 2^{30}
+
+% todo: dimexpr
+
+\def\doMPreciprocal % replace \MPscratchDim with its reciprocal
+ {\ifdim\MPscratchDim=\onepoint \else
+ \MPadjustdimen
+ \scratchcounter\MPnumerator
+ \divide\scratchcounter\MPscratchDim
+ \MPscratchDim1\scratchcounter % 1 needed !
+ \MPreadjustdimen
+ \fi}
+
+%OLD \def\presetMPconcat
+%OLD {\dimen 0=\gMPs1\onepoint \doMPreducedimen 0 % r_x
+%OLD \dimen 2=\gMPs2\onepoint \doMPreducedimen 2 % s_x
+%OLD \dimen 4=\gMPs3\onepoint \doMPreducedimen 4 % s_y
+%OLD \dimen 6=\gMPs4\onepoint \doMPreducedimen 6 % r_y
+%OLD \dimen 8=\gMPs5\onepoint \doMPreducedimen 8 % t_x
+%OLD \dimen10=\gMPs6\onepoint \doMPreducedimen10 } % t_y
+%OLD
+%OLD \def\presetMPscale
+%OLD {\dimen 0=\gMPs1\onepoint \doMPreducedimen 0
+%OLD \dimen 2 \zeropoint
+%OLD \dimen 4 \zeropoint
+%OLD \dimen 6=\gMPs2\onepoint \doMPreducedimen 6
+%OLD \dimen 8 \zeropoint
+%OLD \dimen10 \zeropoint}
+
+\def\presetMPconcat
+ {\dimen 0=\gMPs1\onepoint % s_x
+ \dimen 2=\gMPs2\onepoint % r_x
+ \dimen 4=\gMPs3\onepoint % r_y
+ \dimen 6=\gMPs4\onepoint % s_y
+ \dimen 8=\gMPs5\onepoint % t_x
+ \dimen10=\gMPs6\onepoint} % t_y
+
+\def\presetMPscale
+ {\dimen 0=\gMPs1\onepoint
+ \dimen 2 \zeropoint
+ \dimen 4 \zeropoint
+ \dimen 6=\gMPs2\onepoint
+ \dimen 8 \zeropoint
+ \dimen10 \zeropoint}
+
+\def\noMPtranslate % use this one grouped
+ {\dimen 8 \zeropoint % t_x
+ \dimen10 \zeropoint} % t_y
+
+%D \starttyping
+%D \def\doMPconcat#1#2#3#4%
+%D {\dimen12=#1 pt \doMPreducedimen12 % p_x
+%D \dimen14=#3 pt \doMPreducedimen14 % p_y
+%D %
+%D \dimen16 \dimen 0
+%D \multiply \dimen16 \dimen 6
+%D \dimen20 \dimen 2
+%D \multiply \dimen20 \dimen 4
+%D \advance \dimen16 -\dimen20
+%D %
+%D \dimen18 \dimen12
+%D \multiply \dimen18 \dimen 6
+%D \dimen20 \dimen14
+%D \multiply \dimen20 \dimen 4
+%D \advance \dimen18 -\dimen20
+%D \dimen20 \dimen 4
+%D \multiply \dimen20 \dimen10
+%D \advance \dimen18 \dimen20
+%D \dimen20 \dimen 6
+%D \multiply \dimen20 \dimen 8
+%D \advance \dimen18 -\dimen20
+%D %
+%D \multiply \dimen12 -\dimen 2
+%D \multiply \dimen14 \dimen 0
+%D \advance \dimen12 \dimen14
+%D \dimen20 \dimen 2
+%D \multiply \dimen20 \dimen 8
+%D \advance \dimen12 \dimen20
+%D \dimen20 \dimen 0
+%D \multiply \dimen20 \dimen10
+%D \advance \dimen12 -\dimen20
+%D %
+%D \doMPreducedimen16
+%D \divide \dimen18 \dimen16 \doMPexpanddimen18
+%D \divide \dimen12 \dimen16 \doMPexpanddimen12
+%D %
+%D \edef#2{\withoutpt\the\dimen18}% % p_x^\prime
+%D \edef#4{\withoutpt\the\dimen12}} % p_y^\prime
+%D \stoptyping
+
+%D The following optimization resulted from some tests by
+%D and email exchanges with Sanjoy Mahajan.
+%D
+%D \starttyping
+%D \def\doMPconcat#1#2#3#4%
+%D {\dimen12=#1 pt \doMPreducedimen12 % p_x
+%D \dimen14=#3 pt \doMPreducedimen14 % p_y
+%D %
+%D \dimen16 \dimen 0
+%D \multiply \dimen16 \dimen 6
+%D \dimen20 \dimen 2
+%D \multiply \dimen20 \dimen 4
+%D \advance \dimen16 -\dimen20
+%D %
+%D \dimen18 \dimen12
+%D \multiply \dimen18 \dimen 6
+%D \dimen20 \dimen14
+%D \multiply \dimen20 \dimen 4
+%D \advance \dimen18 -\dimen20
+%D \dimen20 \dimen 4
+%D \multiply \dimen20 \dimen10
+%D \advance \dimen18 \dimen20
+%D \dimen20 \dimen 6
+%D \multiply \dimen20 \dimen 8
+%D \advance \dimen18 -\dimen20
+%D %
+%D \multiply \dimen12 -\dimen 2
+%D \multiply \dimen14 \dimen 0
+%D \advance \dimen12 \dimen14
+%D \dimen20 \dimen 2
+%D \multiply \dimen20 \dimen 8
+%D \advance \dimen12 \dimen20
+%D \dimen20 \dimen 0
+%D \multiply \dimen20 \dimen10
+%D \advance \dimen12 -\dimen20
+%D %
+%D %\ifdim\dimen16>1pt % oeps, can be < 1pt too
+%D \ifdim\dimen16=1pt \else
+%D \ifdim\dimen16>\MPconcatfactor pt
+%D \doMPreducedimen16
+%D \divide \dimen18 \dimen16 \doMPexpanddimen18
+%D \divide \dimen12 \dimen16 \doMPexpanddimen12
+%D \else
+%D \divide \dimen18 \dimen16 \doMPexpanddimen18 \doMPexpanddimen18
+%D \divide \dimen12 \dimen16 \doMPexpanddimen12 \doMPexpanddimen12
+%D \fi
+%D \fi
+%D %
+%D \edef#2{\withoutpt\the\dimen18}% % p_x^\prime
+%D \edef#4{\withoutpt\the\dimen12}} % p_y^\prime
+%D \stoptyping
+%D
+%D But, this one is still too inaccurate, so we now have:
+
+% \def\doMPconcat#1#2#3#4%
+% {\dimen12=#1pt % p_x
+% \dimen14=#3pt % p_y
+% %
+% % we should test for >-1024 too, but for the moment take the gamble
+% \chardef\MPfactor1\ifdim\dimen12<1024pt \ifdim\dimen14<1024pt 6\fi\fi
+% %
+% \multiply\dimen12 \MPfactor
+% \multiply\dimen14 \MPfactor
+% %
+% \doMPreducedimen12
+% \doMPreducedimen14
+% %
+% \dimen16 \dimen 0
+% \multiply \dimen16 \dimen 6
+% \dimen20 \dimen 2
+% \multiply \dimen20 \dimen 4
+% \advance \dimen16 -\dimen20
+% %
+% \dimen18 \dimen12
+% \multiply \dimen18 \dimen 6
+% \dimen20 \dimen14
+% \multiply \dimen20 \dimen 4
+% \advance \dimen18 -\dimen20
+% \dimen20 \dimen 4
+% \multiply \dimen20 \dimen10
+% \advance \dimen18 \dimen20
+% \dimen20 \dimen 6
+% \multiply \dimen20 \dimen 8
+% \advance \dimen18 -\dimen20
+% %
+% \multiply \dimen12 -\dimen 2
+% \multiply \dimen14 \dimen 0
+% \advance \dimen12 \dimen14
+% \dimen20 \dimen 2
+% \multiply \dimen20 \dimen 8
+% \advance \dimen12 \dimen20
+% \dimen20 \dimen 0
+% \multiply \dimen20 \dimen10
+% \advance \dimen12 -\dimen20
+% %
+% \ifdim\dimen16=1pt \else
+% \ifdim\dimen16>\MPconcatfactor pt
+% \doMPreducedimen16
+% \divide \dimen18 \dimen16 \doMPexpanddimen18
+% \divide \dimen12 \dimen16 \doMPexpanddimen12
+% \else
+% \divide \dimen18 \dimen16 \doMPexpanddimen18 \doMPexpanddimen18
+% \divide \dimen12 \dimen16 \doMPexpanddimen12 \doMPexpanddimen12
+% \fi
+% \fi
+% %
+% \divide\dimen18 \MPfactor
+% \divide\dimen12 \MPfactor
+% %
+% \edef#2{\withoutpt\the\dimen18}% % p_x^\prime
+% \edef#4{\withoutpt\the\dimen12}} % p_y^\prime
+
+%D We cannot use \type {\beginETEX} here since in plain we
+%D get \type {\outer} problems, sigh.
+
+%OLD \beginTEX
+%OLD
+%OLD \def\MPcriteriumA {512pt} % scale
+%OLD \def\MPcriteriumB {2pt} % scale
+%OLD
+%OLD \endTEX
+%OLD
+%OLD \ifx\MPcriteriumA\undefined
+%OLD
+%OLD \newdimen\MPcriteriumA \MPcriteriumA=512pt
+%OLD \newdimen\MPcriteriumB \MPcriteriumB= 2pt
+%OLD
+%OLD \fi
+
+%OLD \def\doMPconcat#1#2#3#4%
+%OLD {\dimen12=#1pt % p_x
+%OLD \dimen14=#3pt % p_y
+%OLD %
+%OLD \chardef\MPfactor\zerocount
+%OLD \ifdim\dimen4<\MPcriteriumB\ifdim\dimen4>-\MPcriteriumB
+%OLD \ifdim\dimen6<\MPcriteriumB\ifdim\dimen6>-\MPcriteriumB
+%OLD \ifdim\dimen8<\MPcriteriumB\ifdim\dimen8>-\MPcriteriumB
+%OLD \ifdim\dimen10<\MPcriteriumB\ifdim\dimen10>-\MPcriteriumB
+%OLD \chardef\MPfactor\plusone
+%OLD \fi\fi
+%OLD \fi\fi
+%OLD \fi\fi
+%OLD \fi\fi
+%OLD \ifcase\MPfactor % spurious 0 removed
+%OLD \chardef\MPfactor\plusone
+%OLD \ifdim\dimen12<\MPcriteriumA\ifdim\dimen12>-\MPcriteriumA
+%OLD \ifdim\dimen14<\MPcriteriumA\ifdim\dimen14>-\MPcriteriumA
+%OLD \chardef\MPfactor16
+%OLD \fi\fi
+%OLD \fi\fi
+%OLD \fi
+%OLD %
+%OLD \multiply\dimen12 \MPfactor
+%OLD \multiply\dimen14 \MPfactor
+%OLD %
+%OLD \doMPreducedimen12
+%OLD \doMPreducedimen14
+%OLD %
+%OLD \dimen16 \dimen 0
+%OLD \multiply \dimen16 \dimen 6
+%OLD \dimen20 \dimen 2
+%OLD \multiply \dimen20 \dimen 4
+%OLD \advance \dimen16 -\dimen20
+%OLD %
+%OLD \dimen18 \dimen12
+%OLD \multiply \dimen18 \dimen 6
+%OLD \dimen20 \dimen14
+%OLD \multiply \dimen20 \dimen 4
+%OLD \advance \dimen18 -\dimen20
+%OLD \dimen20 \dimen 4
+%OLD \multiply \dimen20 \dimen10
+%OLD \advance \dimen18 \dimen20
+%OLD \dimen20 \dimen 6
+%OLD \multiply \dimen20 \dimen 8
+%OLD \advance \dimen18 -\dimen20
+%OLD %
+%OLD \multiply \dimen12 -\dimen 2
+%OLD \multiply \dimen14 \dimen 0
+%OLD \advance \dimen12 \dimen14
+%OLD \dimen20 \dimen 2
+%OLD \multiply \dimen20 \dimen 8
+%OLD \advance \dimen12 \dimen20
+%OLD \dimen20 \dimen 0
+%OLD \multiply \dimen20 \dimen10
+%OLD \advance \dimen12 -\dimen20
+%OLD %
+%OLD \ifdim\dimen16=\onepoint \else
+%OLD \ifdim\dimen16>\MPconcatfactor \onepoint \relax
+%OLD \doMPreducedimen16
+%OLD \divide \dimen18 \dimen16 \doMPexpanddimen18
+%OLD \divide \dimen12 \dimen16 \doMPexpanddimen12
+%OLD \else
+%OLD \divide \dimen18 \dimen16 \doMPexpanddimen18 \doMPexpanddimen18
+%OLD \divide \dimen12 \dimen16 \doMPexpanddimen12 \doMPexpanddimen12
+%OLD \fi
+%OLD \fi
+%OLD %
+%OLD \divide\dimen18 \MPfactor
+%OLD \divide\dimen12 \MPfactor
+%OLD %
+%OLD \edef#2{\withoutpt\the\dimen18}% % p_x^\prime
+%OLD \edef#4{\withoutpt\the\dimen12}} % p_y^\prime
+
+%D DHL: Ideally, $r_x$, $r_y$, $s_x4, $s_y$ should be in macros, not
+%D dimensions (they are scalar quantities after all, not lengths). I
+%D suppose the authors decided to do calculations with integer
+%D arithmetic instead of using real factors because it's faster.
+%D However, the actual macros test slower, possibly because I've
+%D omitted three nested loops. In my test files, my approach is more
+%D accurate. It is also far simpler and overflow does not seem to be a
+%D significant concern. The scale factors written by Metapost are (?)
+%D always $<=1$ (it scales coordinates internally) and coordinates are
+%D always likely to be less than \type {\maxdimen}.
+%D
+%D If this should ever cause problems, the scale factors can be reduced.
+
+\def\doMPconcat#1#2#3#4%
+ {\dimen12=#1pt % p_x % #1\onepoint
+ \dimen14=#3pt % p_y % #3\onepoint
+ \advance\dimen12 -\dimen8 % p_x - t_x
+ \advance\dimen14 -\dimen10 % p_y - t_y
+ \dimen18=\withoutpt\the\dimen6 \dimen12 % s_y(p_x - t_x)
+ \advance\dimen18 -\withoutpt\the\dimen4 \dimen14 % - r_y(p_y-t_y)
+ \dimen14=\withoutpt\the\dimen0 \dimen14 % s_x(p_y-t_y)
+ \advance\dimen14 -\withoutpt\the\dimen2 \dimen12 % - r_x(p_x-t_x)
+ % \MPscratchDim contains precomputed 1/D:
+ \dimen18=\withoutpt\the\MPscratchDim \dimen18
+ \dimen14=\withoutpt\the\MPscratchDim \dimen14
+ \edef#2{\withoutpt\the\dimen18}% % p_x^\prime
+ \edef#4{\withoutpt\the\dimen14}} % p_y^\prime
+
+%D One reason for Daniel to write this patch was that at small sizes
+%D the accuracy was less than optimal. Here is a test that demonstrates
+%D that his alternative is pretty good:
+%D
+%D \startlinecorrection
+%D \startMPcode
+%D for i = 5cm,1cm,5mm,1mm,.5mm,.1mm,.01mm :
+%D draw fullcircle scaled i withpen pencircle xscaled (i/10) yscaled (i/20) rotated 45 ;
+%D endfor ;
+%D \stopMPcode
+%D \stoplinecorrection
+
+%D The following explanation of the conversion process was
+%D posted to the \PDFTEX\ mailing list by Tanmoy. The original
+%D macro was part of a set of macro's that included sinus and
+%D cosinus calculations as well as scaling and translating. The
+%D \METAPOST\ to \PDF\ conversion however only needs
+%D transformation.
+
+%M \start \switchtobodyfont [ss]
+
+%D Given a point $(U_x, U_y)$ in user coordinates, the business
+%D of \POSTSCRIPT\ is to convert it to device space. Let us say
+%D that the device space coordinates are $(D_x, D_y)$. Then, in
+%D \POSTSCRIPT\ $(D_x, D_y)$ can be written in terms of
+%D $(U_x, U_y)$ in matrix notation, either as
+%D
+%D \placeformula
+%D \startformula
+%D \pmatrix{D_x&D_y&1\cr} = \pmatrix{U_x&U_y&1\cr}
+%D \pmatrix{s_x&r_x&0\cr
+%D r_y&s_y&0\cr
+%D t_x&t_y&1\cr}
+%D \stopformula
+%D
+%D or
+%D
+%D \placeformula
+%D \startformula
+%D \pmatrix{D_x\cr D_y\cr 1} = \pmatrix{s_x&r_y&t_x\cr
+%D r_x&s_y&t_y\cr
+%D 0 &0 &1 \cr}
+%D \pmatrix{U_x\cr
+%D U_y\cr
+%D 1 \cr}
+%D \stopformula
+%D
+%D both of which is a shorthand for the same set of equations:
+%D
+%D \placeformula
+%D \startformula
+%D D_x = s_x U_x + r_y U_y + t_x
+%D \stopformula
+%D
+%D \placeformula
+%D \startformula
+%D D_y = r_x U_x + s_y U_y + t_y
+%D \stopformula
+%D
+%D which define what is called an `affine transformation'.
+%D
+%D \POSTSCRIPT\ represents the `transformation matrix' as a
+%D six element matrix instead of a $3\times 3$ array because
+%D three of the elements are always~0, 0 and~1. Thus the above
+%D transformation is written in postscript as $[s_x\, r_x\,
+%D r_y\, s_y\, t_x\, t_y]$. However, when doing any
+%D calculations, it is useful to go back to the original
+%D matrix notation (whichever: I will use the second) and
+%D continue from there.
+%D
+%D As an example, if the current transformation matrix is
+%D $[s_x\, r_x\, r_y\, s_y\, t_x\, t_y]$ and you say \typ{[a b
+%D c d e f] concat}, this means:
+%D
+%D \startnarrower
+%D Take the user space coordinates and transform them to an
+%D intermediate set of coordinates using array $[a\, b\, c\, d\,
+%D e\, f]$ as the transformation matrix.
+%D
+%D Take the intermediate set of coordinates and change them to
+%D device coordinates using array $[s_x\, r_x\, r_y\, s_y\, t_x\, t_y]$
+%D as the transformation matrix.
+%D \stopnarrower
+%D
+%D Well, what is the net effect? In matrix notation, it is
+%D
+%D \placeformula
+%D \startformula
+%D \pmatrix{I_x\cr I_y\cr 1\cr} = \pmatrix{a&c&e\cr
+%D b&d&f\cr
+%D 0&0&1\cr}
+%D \pmatrix{U_x\cr
+%D U_y\cr
+%D 1 \cr}
+%D \stopformula
+%D
+%D \placeformula
+%D \startformula
+%D \pmatrix{D_y\cr D_y\cr 1\cr} = \pmatrix{s_x&r_y&t_x\cr
+%D r_x&s_y&t_y\cr
+%D 0 &0 &1 \cr}
+%D \pmatrix{I_x\cr
+%D I_y\cr
+%D 1 \cr}
+%D \stopformula
+%D
+%D where $(I_x, I_y)$ is the intermediate coordinate.
+%D
+%D Now, the beauty of the matrix notation is that when there is
+%D a chain of such matrix equations, one can always compose
+%D them into one matrix equation using the standard matrix
+%D composition law. The composite matrix from two matrices can
+%D be derived very easily: the element in the $i$\high{th}
+%D horizontal row and $j$\high{th} vertical column is
+%D calculated by`multiplying' the $i$\high{th} row of the first
+%D matrix and the $j$\high{th} column of the second matrix (and
+%D summing over the elements). Thus, in the above:
+%D
+%D \placeformula
+%D \startformula
+%D \pmatrix{D_x\cr D_y\cr 1} = \pmatrix{s_x^\prime&r_y^\prime&t_x^\prime\cr
+%D r_x^\prime&s_y^\prime&t_y^\prime\cr
+%D 0 &0 &0 \cr}
+%D \pmatrix{U_x\cr
+%D U_y\cr
+%D 1 \cr}
+%D \stopformula
+%D
+%D with
+%D
+%D \placeformula
+%D \startformula
+%D \eqalign
+%D {s_x^\prime & = s_x a + r_y b \cr
+%D r_x^\prime & = r_x a + s_y b \cr
+%D r_y^\prime & = s_x c + r_y d \cr
+%D s_y^\prime & = r_x c + s_y d \cr
+%D t_x^\prime & = s_x e + r_y f + t_x \cr
+%D t_y^\prime & = r_x e + s_y f + t_y \cr}
+%D \stopformula
+
+%D In fact, the same rule is true not only when one is going
+%D from user coordinates to device coordinates, but whenever
+%D one is composing two `transformations' together
+%D (transformations are `associative'). Note that the formula
+%D is not symmetric: you have to keep track of which
+%D transformation existed before (i.e.\ the equivalent of
+%D $[s_x\, r_x\, r_y\, s_y\, t_x\, t_y]$) and which was
+%D specified later (i.e.\ the equivalent of $[a\, b\, c\, d\,
+%D e\, f]$). Note also that the language can be rather
+%D confusing: the one specified later `acts earlier',
+%D converting the user space coordinates to intermediate
+%D coordinates, which are then acted upon by the pre||existing
+%D transformation. The important point is that order of
+%D transformation matrices cannot be flipped (transformations
+%D are not `commutative').
+%D
+%D Now what does it mean to move a transformation matrix
+%D before a drawing? What it means is that given a point
+%D $(P_x, P_y)$ we need a different set of coordinates
+%D $(P_x^\prime, P_y^\prime)$ such that if the transformation
+%D acts on $(P_x^\prime, P_y^\prime)$, they produce $(P_x,
+%D P_y)$. That is we need to solve the set of equations:
+%D
+%D \placeformula
+%D \startformula
+%D \pmatrix{P_x\cr P_y\cr 1\cr} = \pmatrix{s_x&r_y&t_x\cr
+%D r_x&s_y&t_y\cr
+%D 0 &0 &1 \cr}
+%D \pmatrix{P_x^\prime\cr
+%D P_y^\prime\cr
+%D 1 \cr}
+%D \stopformula
+%D
+%D Again matrix notation comes in handy (i.e. someone has
+%D already solved the problem for us): we need the inverse
+%D transformation matrix. The inverse transformation matrix can
+%D be calculated very easily:
+%D
+%D \placeformula
+%D \startformula
+%D \pmatrix{P_x^\prime\cr P_y^\prime\cr 1\cr} =
+%D \pmatrix{s_x^\prime&r_y^\prime&t_x^\prime\cr
+%D r_x^\prime&s_y^\prime&t_y^\prime\cr
+%D 0 &0 &1 \cr}
+%D \pmatrix{P_x\cr
+%D P_y\cr
+%D 1 \cr}
+%D \stopformula
+%D
+%D where, the inverse transformation matrix is given by
+%D
+%D \placeformula
+%D \startformula
+%D \eqalign
+%D {D & = s_x s_y - r_x r_y \cr
+%D s_x^\prime & = s_y / D \cr
+%D s_y^\prime & = s_x / D \cr
+%D r_x^\prime & = - r_x / D \cr
+%D r_y^\prime & = - r_y / D \cr
+%D t_x^\prime & = ( - s_y t_x + r_y t_y ) / D \cr
+%D t_y^\prime & = ( r_x t_x - s_x t_y ) / D \cr}
+%D \stopformula
+%D
+%D And you can see that when expanded out, this does
+%D give the formulas:
+%D
+%D \placeformula
+%D \startformula
+%D P_x^\prime = { { s_y(p_x-t_x) + r_y(t_y-p_y) } \over
+%D { s_x s_y-r_x r_y } }
+%D \stopformula
+%D
+%D \placeformula
+%D \startformula
+%D P_y^\prime = { { s_x(p_y-t_y) + r_x(t_x-p_x) } \over
+%D { s_x*s_y-r_x*r_y } }
+%D \stopformula
+%D
+%D The code works by representing a real number by converting
+%D it to a dimension to be put into a \DIMENSION\ register: 2.3 would
+%D be represented as 2.3pt for example. In this scheme,
+%D multiplying two numbers involves multiplying the \DIMENSION\
+%D registers and dividing by 65536. Accuracy demands that the
+%D division be done as late as possible, but overflow
+%D considerations need early division.
+%D
+%D Division involves dividing the two \DIMENSION\ registers and
+%D multiplying the result by 65536. Again, accuracy would
+%D demand that the numerator be multiplied (and|/|or the
+%D denominator divided) early: but that can lead to overflow
+%D which needs to be avoided.
+%D
+%D If nothing is known about the numbers to start with (in
+%D concat), I have chosen to divide the 65536 as a 256 in each
+%D operand. However, in the series calculating the sine and
+%D cosine, I know that the terms are small (because I never
+%D have an angle greater than 45 degrees), so I chose to
+%D apportion the factor in a different way.
+
+%M \stop
+
+%D The path is output using the values saved on the stack. If
+%D needed, all coordinates are recalculated.
+
+\def\finishMPpath
+ {\PDFcode{\ifcase\finiMPpath W n\or S\or f\or B\fi}}
+
+\def\processMPpath
+ {\checkMPpath
+ \ifcase\nofMPsegments\else
+ \flushMPpath
+ \closeMPpath
+ \finishMPpath
+ \fi
+ \let\handleMPsequence\dohandleMPsequence
+ \resetMPstack
+ \nofMPsegments\zerocount
+ \handleMPsequence}
+
+%D The following \METAPOST\ code is quite valid but, when
+%D processed and converted to \PDF, will make a file
+%D unprintable on a Hewlett Packard printer (from Acrobat
+%D $v<=5$). Who is to blame, the driver of the OS layer in
+%D between, is hard to determine, so we add an additional
+%D check.
+%D
+%D \starttyping
+%D clip currentpicture to origin -- cycle ;
+%D setbounds currentpicture to fullsquare scaled 5cm ;
+%D \stoptyping
+
+\def\checkMPpath
+ {\ifcase\finiMPpath
+ \ifnum\nofMPsegments<3 % n is one ahead
+ \message{omitting zero clip path}%
+ \nofMPsegments\zerocount
+ \fi
+ \fi}
+
+%D In \PDF\ the \type{cm} operator must precede the path
+%D specification. We therefore can output the \type{cm} at
+%D the moment we encounter it.
+
+\def\handleMPpathconcat
+ {\presetMPconcat
+ \PDFcode{\gMPs1 \gMPs2 \gMPs3 \gMPs4 \gMPs5 \gMPs6 cm}%
+ \resetMPstack}
+
+\def\handleMPpathscale
+ {\presetMPscale
+ \PDFcode{\gMPs1 0 0 \gMPs2 0 0 cm}%
+ \resetMPstack}
+
+%D This macro interprets the path and saves it as compact as
+%D possible.
+
+\def\dohandleMPpath#1%
+ {\ifcase\lccode`#1\relax
+ \@EA\dohandleMPpathA
+ \else
+ \@EA\dohandleMPpathB
+ \fi#1}
+
+%\def\dohandleMPpathA#1 %
+% {\setMPargument{#1}%
+% \handleMPsequence}
+
+\let\dohandleMPpathA\setMPsequence
+
+\def\dohandleMPpathB#1 %
+ {\def\somestring{#1}%
+ \ifx\somestring\PSlineto
+ \setMPkeyword0
+ \else\ifx\somestring\PScurveto
+ \setMPkeyword1
+ \else\ifx\somestring\PSrlineto
+ \setMPkeyword2
+ \else\ifx\somestring\PSmoveto
+ \setMPkeyword3
+ \else\ifx\somestring\PSclip
+ % \chardef\finiMPpath0 % already
+ \let\handleMPsequence\processMPpath
+ \else\ifx\somestring\PSgsave
+ \chardef\finiMPpath3
+ \else\ifx\somestring\PSgrestore
+ \else\ifx\somestring\PSfill
+ \ifcase\finiMPpath
+ \chardef\finiMPpath2
+ \let\handleMPsequence\processMPpath
+ \fi
+ \else\ifx\somestring\PSstroke
+ \ifcase\finiMPpath
+ \chardef\finiMPpath1
+ \fi
+ \let\handleMPsequence\processMPpath
+ \else\ifx\somestring\PSclosepath
+ \def\closeMPpath{\PDFcode{h}}%
+ \else\ifx\somestring\PSconcat
+ \let\flushMPpath\flushconcatMPpath
+ \handleMPpathconcat
+ \else\ifx\somestring\PSscale
+ \let\flushMPpath\flushconcatMPpath
+ \handleMPpathscale
+ \fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi
+ \handleMPsequence}
+
+%D The main conversion command is:
+%D
+%D \starttyping
+%D \convertMPtoPDF {filename} {x scale} {y scale}
+%D \stoptyping
+%D
+%D The dimensions are derived from the bounding box. So we
+%D only have to say:
+%D
+%D \starttyping
+%D \convertMPtoPDF{mp-pra-1.eps}{1}{1}
+%D \convertMPtoPDF{mp-pra-1.eps}{.5}{.5}
+%D \stoptyping
+
+%D \macros
+%D {makeMPintoPDFobject,lastPDFMPobject}
+%D
+%D For experts there are a few more options. When attributes
+%D are to be added, the code must be embedded in an object
+%D accompanied with the appropriate directives. One can
+%D influence this process with \type {\makeMPintoPDFobject}.
+%D
+%D This option defaults to~0, because \CONTEXT\ takes care
+%D of objects at another level, which saves some bytes.
+%D
+%D \starttabulate[|l|l|p|]
+%D \NC 0 \NC never \NC don't use an object \NC\NR
+%D \NC 1 \NC always \NC always use an object \NC\NR
+%D \NC 2 \NC optional \NC use object when needed \NC\NR
+%D \stoptabulate
+%D
+%D The last object number used is avaliable in the macro
+%D \type {\lastPDFMPobject}.
+
+\ifx\makeMPintoPDFobject\undefined \chardef\makeMPintoPDFobject=0 \fi
+
+\def\lastPDFMPobject{0}
+
+%D The additional code needed can be made available in the
+%D (global) macro \type {\currentPDFresources}.
+
+\let\currentPDFresources\empty
+
+\newtoks\everyMPtoPDFconversion
+
+\def\convertMPtoPDF % #1#2#3%
+ {\bgroup
+ \ifx\pdfdecimaldigits\undefined\else \pdfdecimaldigits=5 \fi % new
+ \setbox\scratchbox\vbox\bgroup
+ \forgetall
+ \offinterlineskip
+ \startMPresources
+ \doprocessMPtoPDFfile} %
+
+%D The next one is kind of private and probably will become obsolete):
+
+\def\processMPtoPDFfile % file xscale yscale
+ {\bgroup
+ \let\finishMPgraphic\egroup
+ \doprocessMPtoPDFfile}
+
+\def\doprocessMPtoPDFfile#1#2#3% file xscale yscale
+ {% the following line is needed for latex where onepoint is not
+ % onepoint but a number (maxdimen); some day i'll make a latex
+ % variant of this file so that i no longer have to deal with such
+ % issues; then i'll also speed up this module using a few context
+ % tricks
+ %
+ \let\onepoint\onerealpoint
+ %
+ \setMPspecials
+ \the\everyMPtoPDFconversion
+ \catcode`\^^M=\@@endofline
+ \startMPscanning
+ \let\do\empty
+ \xdef\MPxscale{#2}%
+ \xdef\MPyscale{#3}%
+ \xdef\MPxoffset{0}%
+ \xdef\MPyoffset{0}%
+ \xdef\MPyshift{\zeropoint}%
+ \donefalse
+ \let\handleMPsequence\dohandleMPsequence
+ \message{[MP to PDF]}% was: [MP to PDF #1] but there is a (#1) anyway
+ \input#1\relax}
+
+% strange rounding/clip in pdftex/viewer
+%
+% \def\finishMPgraphic
+% {\stopMPresources
+% \egroup
+% \ifx\pdftexversion\undefined\else\ifnum\pdftexversion<14 % for the moment
+% \chardef\makeMPintoPDFobject=0
+% \fi\fi
+% \ifcase\makeMPintoPDFobject\or\or\ifx\currentPDFresources\empty\else
+% \chardef\makeMPintoPDFobject=1
+% \fi\fi
+% \setbox\scratchbox=\vbox
+% {\forgetall
+% \hbox
+% {\PDFcode{q \MPxscale\space 0 0 \MPyscale\space \MPxoffset\space \MPyoffset\space cm}%
+% \lower\MPyshift\box\scratchbox % unscaled shift
+% \PDFcode{Q}}}%
+% \ht\scratchbox\MPheight
+% \wd\scratchbox\MPwidth
+% \dp\scratchbox\zeropoint
+% \ifcase\makeMPintoPDFobject
+% \box\scratchbox
+% \or
+% \immediate\pdfxform resources{\currentPDFresources}\scratchbox
+% \xdef\lastPDFMPobject{\the\pdflastxform}%
+% \pdfrefxform\lastPDFMPobject
+% \global\let\currentPDFresources\empty
+% \else
+% \box\scratchbox
+% \fi
+% \egroup}
+%
+% funny clip in viewer
+%
+% \setbox\scratchbox=\vbox
+% {\forgetall
+% \dimen0=\MPllx bp
+% \dimen2=\MPlly bp
+% \setbox\scratchbox=\hbox{\hskip-\dimen0\raise-\dimen2\box\scratchbox}%
+% \ht\scratchbox=\zeropoint
+% \dp\scratchbox=\zeropoint
+% \wd\scratchbox=\zeropoint
+% \hbox
+% {\PDFcode{q \MPxscale\space 0 0 \MPyscale\space 0 0 cm}%
+% \lower\MPshift\box\scratchbox
+% \PDFcode{Q}}}%
+
+% \let\PDFMPformoffset\zeropoint
+
+\def\PDFMPformoffset
+ {\ifx\objectoffset\undefined\zeropoint\else\objectoffset\fi}
+
+\def\finishMPgraphic
+ {\stopMPresources
+ \egroup
+ \setbox\scratchbox\vbox
+ {\forgetall
+ \hbox
+ {\PDFcode{q \MPxscale\space 0 0 \MPyscale\space \MPxoffset\space \MPyoffset\space cm}%
+ \lower\MPyshift\box\scratchbox % unscaled shift
+ \PDFcode{Q}}}%
+ \ht\scratchbox\MPheight
+ \wd\scratchbox\MPwidth
+ \dp\scratchbox\zeropoint\relax
+ \dopackageMPgraphic\scratchbox
+ \egroup
+ \endinput}
+
+%D Alternative for \PDFTEX. We cannot come up with something more contexy
+%D because this module is also used in \LATEX.
+
+\def\dopackageMPgraphic#1% #1 = boxregister
+ {%\ifx\pdfxform\undefined
+ % \chardef\makeMPintoPDFobject\zerocount % no pdftex at all
+ %\else\ifx\pdftexversion\undefined
+ % \chardef\makeMPintoPDFobject\zerocount % no pdftex at all
+ %\else\ifnum\pdftexversion<14
+ % \chardef\makeMPintoPDFobject\zerocount % no resource support
+ %\else
+ % % keep the default value
+ %\fi\fi\fi
+ \ifcase\makeMPintoPDFobject\or\or\ifx\currentPDFresources\empty\else
+ % an existing value of 2 signals object support (set elsewhere)
+ \chardef\makeMPintoPDFobject\plusone
+ \fi\fi
+ \ifcase\makeMPintoPDFobject
+ \box#1%
+ \or
+ \scratchdimen\PDFMPformoffset\relax
+ \ifdim\scratchdimen>\zeropoint % compensate for error
+ \setbox#1\vbox spread 2\scratchdimen
+ {\forgetall\vss\hbox spread 2\scratchdimen{\hss\box#1\hss}\vss}%
+ \fi
+ \setMPPDFobject{\currentPDFresources}{#1}%
+ \ifdim\scratchdimen>\zeropoint % compensate for error
+ \vbox to \MPheight
+ {\forgetall\vss\hbox to \MPwidth{\hss\getMPPDFobject\hss}\vss}%
+ \else
+ \getMPPDFobject
+ \fi
+ \global\let\currentPDFresources\empty
+ \else
+ \box#1%
+ \fi}
+
+\def\setMPPDFobject#1#2% resources boxnumber
+ {\ifx\pdfxform\undefined
+ \def\getMPPDFobject{\box#2}%
+ \else\ifx\pdftexversion\undefined
+ \def\getMPPDFobject{\box#2}%
+ \else\ifnum\pdftexversion<14
+ \def\getMPPDFobject{\box#2}%
+ \else
+ \immediate\pdfxform resources{#1}#2%
+ \edef\getMPPDFobject{\noexpand\pdfrefxform\the\pdflastxform}%
+ \fi\fi\fi}
+
+\let\getMPPDFobject\relax
+
+%D \macros
+%D {deleteMPgraphic,
+%D startMPresources,
+%D stopMPresources}
+%D
+%D Here are a few hooks for \CONTEXT\ specific things.
+
+\ifx\deleteMPgraphic\undefined
+ \def\deleteMPgraphic#1{}
+\fi
+
+\ifx\startMPresources\undefined
+ \let\startMPresources\relax
+ \let\stopMPresources\relax
+\fi
+
+%D \macros
+%D {twodigitMPoutput}
+%D
+%D We can limit the precision to two digits after the comma
+%D by saying:
+%D
+%D \starttyping
+%D \twodigitMPoutput
+%D \stoptyping
+%D
+%D This option only works in \CONTEXT\ combined with \ETEX.
+
+\def\twodigitMPoutput
+ {\let\!MP \twodigitrounding
+ \def\!MPgMPs##1{\twodigitrounding{\gMPs##1}}%
+ \def\!MPgMPa##1{\twodigitrounding{\gMPa##1}}}
+
+\let\!MP \empty
+\let\!MPgMPa\gMPa
+\let\!MPgMPs\gMPs
+
+%D This kind of conversion is possible because \METAPOST\
+%D does all the calculations. Converting other \POSTSCRIPT\
+%D files would drive both me and \TEX\ crazy.
+
+\ifx\undefined\StopLatexHack \else \StopLatexHack \fi
+
+\protect \endinput
diff --git a/Master/texmf/doc/pdftex/manual/samplepdf/tmp.pdf b/Master/texmf/doc/pdftex/manual/samplepdf/tmp.pdf
new file mode 100644
index 00000000000..3ce979ebf0c
--- /dev/null
+++ b/Master/texmf/doc/pdftex/manual/samplepdf/tmp.pdf
Binary files differ
diff --git a/Master/texmf/doc/pdftex/pdftex-pdfkeys/Makefile b/Master/texmf/doc/pdftex/pdftex-pdfkeys/Makefile
new file mode 100644
index 00000000000..b2ce911283e
--- /dev/null
+++ b/Master/texmf/doc/pdftex/pdftex-pdfkeys/Makefile
@@ -0,0 +1,29 @@
+# $Id: //depot/Master/texmf-dist/doc/pdftex/base/pdftex-pdfkeys/Makefile#1 $
+
+SOURCE = pdftex-pdfkeys
+PDFLATEX = pdflatex
+THUMBPDF = thumbpdf
+BIBTEX = bibtex
+
+SRCS = ${SOURCE}.tex fdl.tex
+
+##########################################################
+# Rules
+
+all: ${SOURCE}.pdf
+
+${SOURCE}.bbl: ${SOURCE}.tex
+ ${PDFLATEX} ${SOURCE}.tex
+ ${BIBTEX} ${SOURCE}
+
+${SOURCE}.pdf: ${SRCS} ${SOURCE}.bbl
+ ${PDFLATEX} ${SOURCE}.tex
+ ${PDFLATEX} ${SOURCE}.tex
+ ${THUMBPDF} ${SOURCE}.pdf
+ ${PDFLATEX} ${SOURCE}.tex
+
+clean:
+ rm -f *.aux *.blg *.log *.lot *.ilg *.toc *.gls *.glo *.idx *.ind *.brf *.out *.tpt *.inc
+
+realclean: clean
+ rm -f *.tex *.drv *.dvi *.pdf
diff --git a/Master/texmf/doc/pdftex/pdftex-pdfkeys/fdl.tex b/Master/texmf/doc/pdftex/pdftex-pdfkeys/fdl.tex
new file mode 100644
index 00000000000..bbccbb2e73d
--- /dev/null
+++ b/Master/texmf/doc/pdftex/pdftex-pdfkeys/fdl.tex
@@ -0,0 +1,368 @@
+% fdl.tex
+% This file is a chapter. It must be included in a larger document to work
+% properly.
+
+\chapter{GNU Free Documentation License}
+\label{chap:fdl}
+
+Version 1.1, March 2000
+
+ Copyright \copyright\ 2000 Free Software Foundation, Inc.\\
+ 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA\\
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+\section*{Preamble}
+
+The purpose of this License is to make a manual, textbook, or other
+written 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.
+
+\section{Applicability and Definitions}
+
+This License applies to any manual or other work that contains a
+notice placed by the copyright holder saying it can be distributed
+under the terms of this License. The ``Document'', below, refers to any
+such manual or work. Any member of the public is a licensee, and is
+addressed as ``you''.
+
+A ``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 ``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. (For example, 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 ``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.
+
+The ``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 ``Transparent'' copy of the Document means a machine-readable copy,
+represented in a format whose specification is available to the
+general public, whose contents can be viewed and edited directly and
+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 has been designed to thwart or discourage
+subsequent modification by readers is not Transparent. A copy that is
+not ``Transparent'' is called ``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 designed for human modification. Opaque formats include
+PostScript, PDF, 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 produced by some word processors for output
+purposes only.
+
+The ``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.
+
+
+\section{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.
+
+
+\section{Copying in Quantity}
+
+If you publish printed copies 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 publicly-accessible computer-network location containing a complete
+Transparent copy of the Document, free of added material, which the
+general network-using public has access to download anonymously at no
+charge using public-standard network protocols. 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.
+
+
+\section{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:
+
+\begin{itemize}
+
+\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 less than five).
+\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'', and 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 In any section entitled ``Acknowledgements'' or ``Dedications'',
+ preserve the section's title, 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 as ``Endorsements''
+ or to conflict in title with any Invariant Section.
+
+\end{itemize}
+
+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.
+
+
+\section{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.
+
+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.''
+
+
+\section{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.
+
+
+
+\section{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, does not as a whole count as a Modified Version
+of the Document, provided no compilation copyright is claimed for the
+compilation. Such a compilation is called an ``aggregate'', and this
+License does not apply to the other self-contained works thus compiled
+with the Document, on account of their being thus compiled, if they
+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 quarter
+of the entire aggregate, the Document's Cover Texts may be placed on
+covers that surround only the Document within the aggregate.
+Otherwise they must appear on covers around the whole aggregate.
+
+
+\section{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 provided that you also include the
+original English version of this License. In case of a disagreement
+between the translation and the original English version of this
+License, the original English version will prevail.
+
+
+\section{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.
+
+
+\section{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.
+
+\section*{ADDENDUM: How to use this License for your documents}
+
+To use this License in a document you have written, include a copy of
+the License in the document and put the following copyright and
+license notices just after the title page:
+
+\begin{quote}
+
+ Copyright \copyright\ YEAR YOUR NAME.
+ Permission is granted to copy, distribute and/or modify this document
+ under the terms of the GNU Free Documentation License, Version 1.1
+ or any later version published by the Free Software Foundation;
+ with the Invariant Sections being LIST THEIR TITLES, with the
+ Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
+ A copy of the license is included in the section entitled ``GNU
+ Free Documentation License''.
+
+\end{quote}
+
+If you have no Invariant Sections, write ``with no Invariant Sections''
+instead of saying which ones are invariant. If you have no
+Front-Cover Texts, write ``no Front-Cover Texts'' instead of
+``Front-Cover Texts being LIST''; likewise for Back-Cover Texts.
+
+If your document contains nontrivial examples of program code, we
+recommend releasing these examples in parallel under your choice of
+free software license, such as the GNU General Public License,
+to permit their use in free software.
+
diff --git a/Master/texmf/doc/pdftex/pdftex-pdfkeys/pdftex-pdfkeys.bbl b/Master/texmf/doc/pdftex/pdftex-pdfkeys/pdftex-pdfkeys.bbl
new file mode 100644
index 00000000000..d66386716ab
--- /dev/null
+++ b/Master/texmf/doc/pdftex/pdftex-pdfkeys/pdftex-pdfkeys.bbl
@@ -0,0 +1,16 @@
+\input bibnames.sty \input path.sty \ifx \POSTSCRIPT \undefined \def
+ \POSTSCRIPT {{Post\-Script}} \fi\hyphenation{Ker-n-i-ghan Port-able
+ Post-Script Pren-tice Richt-er Spring-er}
+\begin{thebibliography}{1}
+
+\bibitem{Adobe:2000:PRA}
+{Adobe Systems Incorporated}.
+\newblock {\em {PDF} reference: {Adobe} portable document format, version 1.3}.
+\newblock Ad{\-d}i{\-s}on-Wes{\-l}ey, Reading, MA, USA, second edition, 2000.
+
+\bibitem{Adobe:2001:PRA}
+{Adobe Systems Incorporated}.
+\newblock {\em {PDF} reference: {Adobe} portable document format, version 1.4}.
+\newblock Ad{\-d}i{\-s}on-Wes{\-l}ey, Reading, MA, USA, third edition, 2001.
+
+\end{thebibliography}
diff --git a/Master/texmf/doc/pdftex/pdftex-pdfkeys/pdftex-pdfkeys.pdf b/Master/texmf/doc/pdftex/pdftex-pdfkeys/pdftex-pdfkeys.pdf
new file mode 100644
index 00000000000..f25cd03da51
--- /dev/null
+++ b/Master/texmf/doc/pdftex/pdftex-pdfkeys/pdftex-pdfkeys.pdf
Binary files differ
diff --git a/Master/texmf/doc/pdftex/pdftex-pdfkeys/pdftex-pdfkeys.tex b/Master/texmf/doc/pdftex/pdftex-pdfkeys/pdftex-pdfkeys.tex
new file mode 100644
index 00000000000..246b4329318
--- /dev/null
+++ b/Master/texmf/doc/pdftex/pdftex-pdfkeys/pdftex-pdfkeys.tex
@@ -0,0 +1,210 @@
+% $Id: //depot/Master/texmf-dist/doc/pdftex/base/pdftex-pdfkeys/pdftex-pdfkeys.tex#1 $
+% Copyright (c) 2001 Martin Schröder
+% Permission is granted to copy, distribute and/or modify this document
+% under the terms of the GNU Free Documentation License, Version 1.1 or
+% any later version published by the Free Software Foundation; with with
+% no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
+% Texts.
+% A copy of the license is included in the appendix entitled "GNU Free
+% Documentation License".
+%
+% The layout of this document tries to mimic that of the PDF reference.
+\pdfoutput=1
+\pdfcompresslevel=9
+\pdfdecimaldigits=5
+\documentclass[a4paper,oneside,bibtotoc,openany,pdftex]{scrbook}
+\usepackage[latin1]{inputenc}
+\usepackage[pdfpagelabels]{hyperref}
+\usepackage{thumbpdf}
+\usepackage{filecontents}
+\usepackage{ltxtable,booktabs}
+\usepackage{xspace}
+\usepackage{relsize}
+\usepackage{prelim2e}
+\newcommand{\documentversion}{0.12}
+\renewcommand{\PrelimText}{%
+ \textnormal{%
+ \footnotesize%
+ \PrelimTextStyle%
+ Version \documentversion{} -- 2002-05-10
+ }%
+ }
+
+%--------------
+
+\hypersetup{colorlinks,
+ bookmarksnumbered,
+ pdftitle={Additional PDF keys inserted by pdfTeX},
+ pdfauthor={Martin Schröder}}
+
+\newenvironment{keytable}[1]
+% Usage:
+% \begin{filecontents}{foo}
+% \begin{keytable}{caption}
+% \pdfkey...
+% \end{keytable}
+% \end{filecontents}
+% \LTXtable{\textwidth}{foo}
+ {%
+ \begin{longtable}{ll>{\raggedright}X}
+ \caption{#1}\belowpdfbookmark{Table \thetable{} #1}{table:\thetable}\\
+ \toprule
+ \sffamily\slshape Key & \sffamily\slshape Type & \sffamily\slshape Semantics \tabularnewline
+ \midrule\addlinespace[1ex]
+ \endfirsthead
+ \caption[]{(continued)}\\
+ \toprule
+ \sffamily\slshape Key & \sffamily\slshape Type & \sffamily\slshape Semantics \tabularnewline
+ \midrule\addlinespace[1ex]
+ \endhead
+ \bottomrule
+ \endfoot
+ }{\end{longtable}%
+ }
+\newcommand*{\pdfkey}[3]{\bfseries #1 & #2 & #3\tabularnewline}
+
+\newenvironment{history}
+ {%
+ \begin{longtable}{lll>{\raggedright}X}
+ \caption{History}\belowpdfbookmark{Table \thetable{} History}{table:\thetable}\\
+ \toprule
+ Version & When & Who & What \tabularnewline
+ \midrule\addlinespace[1ex]
+ \endfirsthead
+ \caption[]{(continued)}\\
+ \toprule
+ Version & When & Who & What \tabularnewline
+ \midrule\addlinespace[1ex]
+ \endhead
+ \bottomrule
+ \endfoot
+ }{\end{longtable}%
+ }
+\newcommand*{\historyentry}[4]{#1 & #2 & #3 & #4\tabularnewline}
+
+%--------------
+
+\deffootnote{1em}{1em}{\textsuperscript{\normalfont{\thefootnotemark}}}
+
+%--------------
+
+\newcommand{\pt}{pdf\TeX\xspace}
+\newcommand{\eg}{e.\,g.\xspace}
+\newcommand*{\key}[1]{\textsf{\textbf{#1}}\xspace}
+
+%--------------
+\begin{document}
+\frontmatter
+\title{Additional PDF keys inserted by \pt\\[1ex]
+ \relsize{-2} Version \documentversion}
+\author{Martin Schröder%
+ \thanks{ArtCom GmbH\newline
+ Grazer Straße 8\newline
+ 28359 Bremen\newline
+ Germany\newline
+ \texttt{ms@artcom-gmbh.de}}
+ }
+\maketitle
+
+\tableofcontents
+\listoftables
+
+%--------------
+
+\chapter*{Copyright}
+
+Permission is granted to copy, distribute and/or modify this document under the
+terms of the GNU Free Documentation License, Version 1.1 or any later version
+published by the Free Software Foundation; with no Invariant Sections, with no
+Front-Cover Texts, and with no Back-Cover Texts.
+A copy of the license is included in appendix \ref{chap:fdl}.
+
+%--------------
+\mainmatter
+\chapter{Introduction}
+
+A PDF document should contain only the structures and attributes defined in
+the PDF specification \cite{Adobe:2001:PRA}.
+But the specification allows applications to insert additional keys,
+provided they follow certain rules \cite[Appendix F]{Adobe:2001:PRA}.
+
+The most important rule is that developers have to register with Adobe prefixes
+for the keys they want to insert.
+This has been done for \pt: Hans Hagen has registered the prefix ``PTEX''.
+
+As this prefix is all caps keys should start with an additional ``.''.
+
+\section{History}
+\begin{filecontents}{ltxtable.inc}
+\begin{history}
+\historyentry{0.12}
+ {2002-05-10}
+ {Martin Schr\"oder}
+ {Fixed typo in Copyright; refer to \cite{Adobe:2001:PRA}
+ instead of \cite{Adobe:2000:PRA} and updated the terminology.}
+\historyentry{0.11}
+ {2001-11-05}
+ {Martin Schr\"oder}
+ {Added \key{PTEX.InfoDict}}
+\historyentry{0.1}
+ {2001-10-10}
+ {Martin Schr\"oder}
+ {Initial version}
+\end{history}
+\end{filecontents}
+\LTXtable{\textwidth}{ltxtable.inc}
+
+%--------------
+\chapter{XObjects (included PDF)}
+
+\pt generates an XObject for every included PDF.
+The dictionary of this object contains these additional keys:
+
+\begin{filecontents}{ltxtable.inc}
+\begin{keytable}{Attributes in XObjects of included PDF}
+\pdfkey{PTEX.FileName}{string}{The name of the included file as seen by \pt.}
+\pdfkey{PTEX.InfoDict}{dictionary}{\emph{(Indirect)} The document
+ information dictionary of the included
+ PDF.}
+\pdfkey{PTEX.PageNumber}{integer}{The page number of the included file.}
+\end{keytable}
+\end{filecontents}
+\LTXtable{\textwidth}{ltxtable.inc}
+
+%--------------
+\chapter{Document Catalog}
+
+Although it would seem more natural to put this infomation in the document
+information dictionary, the PDF reference says
+\cite[p.\,575]{Adobe:2001:PRA}:
+\begin{quote}
+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 (see Section 3.6.1, Document Catalog).
+\end{quote}
+
+\begin{filecontents}{ltxtable.inc}
+\begin{keytable}{Catalog attributes}
+\pdfkey{PTEX.Fullbanner}{string}{The full version of the \pt binary that
+ produced the file as displayed by
+ \texttt{pdftex -\/-version}, \eg\ ``This is
+ pdfTeX, Version
+ 3.14159-1.00a-pretest-ArtCom-20011008''.\newline
+ This is necessary because the string in the
+ \key{Producer} key in the Info dictionary
+ is rather short, \eg\ ``pdfTeX-1.0a-pdfcrypt''.}
+\end{keytable}
+\end{filecontents}
+\LTXtable{\textwidth}{ltxtable.inc}
+
+%--------------
+\appendix
+\include{fdl}
+
+%--------------
+\backmatter
+\bibliographystyle{plain}
+\bibliography{postscri}
+
+\end{document}