From a540e256be85df29c60ac323d4460c6cde1d9350 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Tue, 3 Jan 2006 00:00:18 +0000 Subject: trunk/Master/texmf/doc git-svn-id: svn://tug.org/texlive/trunk@42 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf/doc/pdftex/NEWS | 400 ++ Master/texmf/doc/pdftex/README | 90 + Master/texmf/doc/pdftex/manual/makefiles.cmd | 13 + Master/texmf/doc/pdftex/manual/pdftex-t.tex | 4833 ++++++++++++++++++++ Master/texmf/doc/pdftex/manual/pdftex-w.pdf | 66 + .../texmf/doc/pdftex/manual/samplepdf/pdfcolor.tex | 158 + Master/texmf/doc/pdftex/manual/samplepdf/pic.pdf | Bin 0 -> 36792 bytes Master/texmf/doc/pdftex/manual/samplepdf/rgb.icc | Bin 0 -> 744 bytes .../texmf/doc/pdftex/manual/samplepdf/samplepdf.0 | 24 + .../doc/pdftex/manual/samplepdf/samplepdf.tex | 1161 +++++ .../texmf/doc/pdftex/manual/samplepdf/supp-mis.tex | 695 +++ .../texmf/doc/pdftex/manual/samplepdf/supp-pdf.tex | 2191 +++++++++ Master/texmf/doc/pdftex/manual/samplepdf/tmp.pdf | Bin 0 -> 3031 bytes Master/texmf/doc/pdftex/pdftex-pdfkeys/Makefile | 29 + Master/texmf/doc/pdftex/pdftex-pdfkeys/fdl.tex | 368 ++ .../doc/pdftex/pdftex-pdfkeys/pdftex-pdfkeys.bbl | 16 + .../doc/pdftex/pdftex-pdfkeys/pdftex-pdfkeys.pdf | Bin 0 -> 132564 bytes .../doc/pdftex/pdftex-pdfkeys/pdftex-pdfkeys.tex | 210 + 18 files changed, 10254 insertions(+) create mode 100644 Master/texmf/doc/pdftex/NEWS create mode 100644 Master/texmf/doc/pdftex/README create mode 100644 Master/texmf/doc/pdftex/manual/makefiles.cmd create mode 100644 Master/texmf/doc/pdftex/manual/pdftex-t.tex create mode 100644 Master/texmf/doc/pdftex/manual/pdftex-w.pdf create mode 100644 Master/texmf/doc/pdftex/manual/samplepdf/pdfcolor.tex create mode 100644 Master/texmf/doc/pdftex/manual/samplepdf/pic.pdf create mode 100644 Master/texmf/doc/pdftex/manual/samplepdf/rgb.icc create mode 100644 Master/texmf/doc/pdftex/manual/samplepdf/samplepdf.0 create mode 100644 Master/texmf/doc/pdftex/manual/samplepdf/samplepdf.tex create mode 100644 Master/texmf/doc/pdftex/manual/samplepdf/supp-mis.tex create mode 100644 Master/texmf/doc/pdftex/manual/samplepdf/supp-pdf.tex create mode 100644 Master/texmf/doc/pdftex/manual/samplepdf/tmp.pdf create mode 100644 Master/texmf/doc/pdftex/pdftex-pdfkeys/Makefile create mode 100644 Master/texmf/doc/pdftex/pdftex-pdfkeys/fdl.tex create mode 100644 Master/texmf/doc/pdftex/pdftex-pdfkeys/pdftex-pdfkeys.bbl create mode 100644 Master/texmf/doc/pdftex/pdftex-pdfkeys/pdftex-pdfkeys.pdf create mode 100644 Master/texmf/doc/pdftex/pdftex-pdfkeys/pdftex-pdfkeys.tex (limited to 'Master/texmf/doc/pdftex') 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 generates a uniformly distributed random + integer value between 0 (inclusive) and (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 sets the random seed to a specific value. + - \pdfnoligatures\f disables ligatures for the loaded font \f. + - Escaping strings: + - \pdfescapestring{} escapes the string so that it can be used as + PDF string. + - \pdfescapename{} escapes the string so that it can be used as PDF + name. + - \pdfescapehex{} converts the string to uppercase hexadecimal + representation. + - \pdfunescapehex{} reverses the effect of \pdfescapehex + - \pdfcreationdate expands to the date string that pdfTeX uses in the info + dict as default. + - \pdffilemoddate{} expands to the modification date of in the + same format as \pdfcreationdate (PDF date format). + - \pdffilesize{} expands to the size of as string. + - \pdfmdfivesum{} or \pdfmdfivesum file {} calculates the md5 + sum (of a string or a file) and converts it to uppercase hexadecimal format + (same as \pdfescapehex). + - \pdffiledump [offset ] [length ] + Expands to a hex dump of the file given in , 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 , which expands to the number in the + corresponding form XObject name. + - \leftmarginkern and \rightmarginkern tell the + margin kern at the left and right side of the horizontal list stored in box + . + - \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 }] {}{} + 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 + 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: + "->" + The position "-1" with an empty string indicates that this entry is not + set. + - \pdfstrcmp{}{} compares two strings and returns the strings "0" if + equals , "-1" if is less than , "1" if is greater than + +- 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) + -> +- 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: + --> [count ] + See http://www.ntg.nl/pipermail/ntg-pdftex/2003-June/000165.html +- The syntax of \pdfobj has been extended: + \pdfobj (h, v, m) + --> reserveobjnum + | [useobjnum ] [] [stream []] + --> + | + 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 and 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 [] (h, v, m) + --> [] [] [] [] + --> 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 , 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, + +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 -o +\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 >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