diff options
Diffstat (limited to 'Master/texmf/doc/pdftex')
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 Binary files differnew file mode 100644 index 00000000000..4f20d12a6d0 --- /dev/null +++ b/Master/texmf/doc/pdftex/manual/samplepdf/pic.pdf diff --git a/Master/texmf/doc/pdftex/manual/samplepdf/rgb.icc b/Master/texmf/doc/pdftex/manual/samplepdf/rgb.icc Binary files differnew file mode 100644 index 00000000000..d9c712f6905 --- /dev/null +++ b/Master/texmf/doc/pdftex/manual/samplepdf/rgb.icc 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 Binary files differnew file mode 100644 index 00000000000..3ce979ebf0c --- /dev/null +++ b/Master/texmf/doc/pdftex/manual/samplepdf/tmp.pdf 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 Binary files differnew file mode 100644 index 00000000000..f25cd03da51 --- /dev/null +++ b/Master/texmf/doc/pdftex/pdftex-pdfkeys/pdftex-pdfkeys.pdf 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} |