diff options
Diffstat (limited to 'systems/doc/pdftex/manual/pdftex-t.tex')
-rw-r--r-- | systems/doc/pdftex/manual/pdftex-t.tex | 5151 |
1 files changed, 5151 insertions, 0 deletions
diff --git a/systems/doc/pdftex/manual/pdftex-t.tex b/systems/doc/pdftex/manual/pdftex-t.tex new file mode 100644 index 0000000000..da2703fe56 --- /dev/null +++ b/systems/doc/pdftex/manual/pdftex-t.tex @@ -0,0 +1,5151 @@ +% interface=english modes=letter,screen output=pdftex +% vim: tw=79 + +% $Id: pdftex-t.tex 790 2018-01-02 00:12:04Z karl $ + +% The number of lines on the title page depends on exactly +% what \PDF\ code is generated. +\setvariables[pdftex][titlepagelines=64] + +\setupoutput + [pdftex] + +%D ConTeXt defaults to 1.5; we want to be maximally 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. + +\setupsynonyms + [abbreviation] + [textstyle=smallcaps, + style=smallcaps, + location=left, + width=broad, + sample=\POSTSCRIPT] + +\setupcapitals + [title=no] + +\def\svnscan $#1 #2 #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} +} + +\svnscan $Id: pdftex-t.tex 790 2018-01-02 00:12:04Z karl $ + +\def\currentpdftex{1.40.18} + +%*********************************************************************** + +\def\eTeX{{$\varepsilon$}-\kern-.125em\TeX} +\def\eg{e.g.} +\def\Eg{E.g.} +\def\PDFReference{{\sl PDF Reference}} % PDF with capital letters + +\abbreviation [AFM] {afm} {Adobe Font Metrics} +\abbreviation [BIBTEX] {Bib\TeX} {Handles bibliographies} +\abbreviation [ASCII] {ascii} {American Standard Code for Information Interchange} +\abbreviation [CONTEXT] {\ConTeXt} {general purpose macro package} +\abbreviation [CTAN] {ctan} {global \TEX\ archive server} +\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 [ISO] {iso} {International Organization for Standardization} +\abbreviation [JBIG] {jbig} {Joint Bi-level Image Experts Group} +\abbreviation [JBIGTWO] {jbig2} {Joint Bi-level Image Experts Group} +\abbreviation [JFIF] {jfif} {JPEG File Interchange Format} +\abbreviation [JPEG] {jpeg} {Joint Photographic Experts Group} +\abbreviation [JPEG] {jpeg} {Joint Photographic Experts Group} +\abbreviation [LATEX] {\LaTeX} {general purpose macro package} +\abbreviation [MAC] {Macintosh} {Macintosh hardware platform} +\abbreviation [MACOSX] {Mac\,OS\,X} {Macintosh operating system version 10} +\abbreviation [MACTEX] {Mac\TeX} {\MAC\ \WEBC\ distribution} +\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] {MiK\TeX} {\WIN\ distribution} +\abbreviation [MLTEX] {ml\TeX} {ML\TeX\ extension to \TEX} +\abbreviation [MPTOPDF] {mptopdf} {\METAPOST\ to \PDF\ conversion tool} +\abbreviation [MSDOS] {ms-dos} {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 [PK] {pk} {Packed bitmap font} +\abbreviation [PNG] {png} {Portable Network Graphics} +\abbreviation [POSIX] {posix} {Portable Operating System Interface} +\abbreviation [PROTEXT] {pro\TeX t} {\WIN\ \WEBC\ distribution based on \MIKTEX} +\abbreviation [PS] {ps} {PostScript} +\abbreviation [POSTSCRIPT] {PostScript} {PostScript} +\abbreviation [PSTOPDF] {PStoPDF} {PostScript to \PDF\ converter (on top of \GHOSTSCRIPT)} +\abbreviation [RGB] {rgb} {Red Green Blue color specification} +\abbreviation [TCX] {tcx} {\TEX\ Character Translation} +\abbreviation [TDS] {tds} {\TEX\ Directory Standard} +\abbreviation [TETEX] {te\TeX} {\TEX\ distribution for \UNIX\ (based on \WEBC)} +\abbreviation [TEXEXEC] {\TeX exec} {\CONTEXT\ command line interface} +\abbreviation [TEXINFO] {Texinfo} {generate typeset documentation from info pages} +\abbreviation [TEXUTIL] {\TeX util} {\CONTEXT\ utility tool} +\abbreviation [TEX] {\TeX} {typographic language and program} +\abbreviation [TEXLIVE] {\TeX\ Live} {\TeX\ Live distribution (multiple platform)} +\abbreviation [TFM] {tfm} {\TEX\ Font Metrics} +\abbreviation [TIF] {tiff} {Tagged Interchange File format} +\abbreviation [TUG] {tug} {\TEX\ Users Group} +\abbreviation [UNIX] {Unix} {Unix platform} +\abbreviation [URL] {url} {Uniform Resource Locator} +\abbreviation [WEBC] {Web2c} {official multi||platform \WEB\ environment} +\abbreviation [WEB] {web} {literate programming environment} +\abbreviation [WIN] {Windows} {Microsoft Windows platform} +\abbreviation [XEMTEX] {XEm\TeX} {\WIN\ \WEBC\ distribution} +\abbreviation [ZIP] {zip} {compressed file format} + +%D It makes sense to predefine the name of the author of \PDFTEX, doesn't it? + +\def\THANH{H\`an Th\^e\llap{\raise 0.5ex\hbox{\'{}}} Th\`anh} + +%D Because they are subjected to change and tend to spoil the visual +%D appearance of the \TEX\ source, \URL's are defined here. + +\useURL [ptex_org] [http://www.pdftex.org] % links to ptex_examples +\useURL [ptex_ctan] [http://ctan.org/pkg/pdftex] +\useURL [ptex_devel] [http://foundry.supelec.fr/projects/pdftex] + +% where bug reports should go: +\useURL [ptex_bugs] [mailto:pdftex@tug.org] [] [pdftex@tug.org] +\useURL [ptex_listinfo] [http://lists.tug.org/pdftex] + +\useURL [kpathsea] [http://tug.org/kpathsea] +\useURL [texlive] [http://tug.org/texlive] +\useURL [web2c] [http://tug.org/web2c] +\useURL [ctan_systems] [http://mirror.ctan.org/systems] +\useURL [win32] [http://mirror.ctan.org/systems/win32] +\useURL [context] [http://www.pragma-ade.com] +\useURL [tex_showcase] [http://tug.org/texshowcase] + +\useURL [pdfreference] [http://www.adobe.com/devnet/pdf/pdf_reference.html] +\useURL [thanh_truetype_tub] [http://tug.org/TUGboat/tb30-1/tb94thanh.pdf] +\useURL [jbig2enc] [https://github.com/agl/jbig2enc] + +%D The primitive definitions are specified a bit fuzzy using the next set of +%D commands. Some day I'll write some proper macros to deal with this. + +% keep next 2 lines as temporary kludge for a while to make \type{} of +% older ConTeXt versions handle these two new primitives; the original +% problem with \type{} is already solved in ConTeXt as of 2006-02-14. +\let\ifpdfabsnum\relax +\let\ifpdfabsdim\relax + +\def\Syntax #1{\strut\kern-.25em{#1}\kern-.25em} +\def\Next {\crlf\hbox to 2em{}\nobreak} +\def\Sugar #1{\unskip\unskip\unskip\kern.25em{#1}\kern.25em\ignorespaces} +% +\def\Lbrace {\Sugar{\tttf\leftargument}} +\def\Literal #1{\Sugar{\type{#1}}} +\def\Means {\Sugar{\mathematics{\rightarrow}}} +\def\Modelist #1{\Sugar{\mathematics{(\hbox{#1})}}} +\def\Optional #1{\Sugar{\mathematics{[\hbox{#1}]}}} +\def\Or {\Sugar{\mathematics{\vert}}} +\def\Rbrace {\Sugar{\tttf\rightargument}} +\def\Tex #1{\Sugar{\type{#1}}} +\def\Whatever #1{\Sugar{\mathematics{(\hbox{#1})}}} + +% hyphenates +\def\Something#1{\Sugar{\mathematics{\langle}\prewordbreak + {#1}\prewordbreak\mathematics{\rangle}}} + +\hbadness=10000 % don't care + +% Break after these chars in urls, not before. +\sethyphenatedurlafter / +\sethyphenatedurlafter . +\sethyphenatedurlafter _ + +% introduced +\def\introduced#1{The primitive was introduced in \PDFTEX\ #1.} + +% to get bookmarks for primitives like \ifpdfprimitive +\appendtoks\def\tex#1{\string\\#1}\to\simplifiedcommands + +%D We typeset the \URL's in a monospaced font. + +\setupurl + [style=type] + +%D The basic layout is pretty simple. Because we want non european readers to +%D read the whole text as well, a letter size based alternative is offered +%D too. Mode switching is taken care of at the command line when running +%D \TEXEXEC. + +\startmode[letter] + + \setuppapersize + [letter][letter] + +\stopmode + +\setuplayout + [topspace=1.5cm, + backspace=2.5cm, + leftmargin=2.5cm, + width=middle, + footer=1.5cm, + header=1.5cm, + height=middle] + +%D For the moment we use the description mechanism to typeset keywords etc. +%D Well, I should have used capitals. + +\definedescription + [description] + [location=serried, + width=broad] + +\definedescription + [PathDescription] + [location=left, + sample=TEXPSHEADERS, + width=broad, + headstyle=type] + +\definehead + [pdftexprimitive] + [subsubsection] + +\setuphead + [pdftexprimitive] + [style=, + before=\blank, + after=\blank, + numbercommand=\SubSub] + +%D This is typically a document where we want to save pages, +%D so we don't start any matter (part) on a new page. + +\setupsectionblock [frontpart] [page=] +\setupsectionblock [bodypart] [page=] +\setupsectionblock [backpart] [page=] + +%D The \type{\SubSub} command is rather simple and generates a triangle. +%D This makes the primitives stand out a bit more. + +\def\SubSub#1{\mathematics{\blacktriangleright}} + +%D But, for non Lucida users, the next one is more safe: + +\def\SubSub#1{\goforwardcharacter} + +%D I could have said: +%D +%D \starttyping +%D \setupsection[section-5][previousnumber=no,bodypartconversion=empty] +%D \setuplabeltext[subsubsection=\mathematics{\blacktriangleright}] +%D \stoptyping +%D +%D but this is less clear. + +%D We use white space, but not too much. + +\setupwhitespace + [medium] + +\setupblank + [medium] + +%D Verbatim things get a small margin. + +\setuptyping + [margin=standard] + +\definetyping + [esctyping] +\setuptyping + [esctyping] + [margin=standard,option=commands,escape=@] + +%D Due to the lots of verbatim we will be a bit more tolerant in breaking +%D paragraphs into lines. + +\setuptolerance + [verytolerant,stretch] + +%D We put the chapter and section numbers in the margin and use bold fonts. + +\setupheads + [alternative=margin] + +\setuphead + [section] + [style=\bfb] + +\setuphead + [subsection] + [style=\bfa] + +%D The small table of contents is limited to section titles and is fully +%D interactive. + +\setuplist + [section] + [criterium=all, + interaction=all, + width=2em, + aligntitle=yes, + alternative=a] + +%D Ah, this manual is in english! + +\mainlanguage + [en] + +%D We use Palatino fonts, because they look so well on the screen. The +%D version generated at \PRAGMA\ uses Optima Nova instead. Both fonts are +%D designed by Hermann Zapf. + +\setupfonthandling [hz] [min=25,max=25,step=5] + +\setupalign + [hz,hanging] + +\startnotmode[atpragma] + + \setupfontsynonym [Serif] [handling=quality] + \setupfontsynonym [SerifBold] [handling=quality] + \setupfontsynonym [SerifSlanted] [handling=quality] + \setupfontsynonym [SerifItalic] [handling=quality] + \setupfontsynonym [SerifBoldSlanted] [handling=quality] + \setupfontsynonym [SerifBoldItalic] [handling=quality] + + %setupfontsynonym [Mono] [handling=quality] % sloooow + + % We use adobe metrics instead of urw metrics because tetex only + % ships the former. Beware, these metrics differ! + + \loadmapfile[context-base.map] + \usetypescript [adobekb] [\defaultencoding] + \usetypescript [palatino][\defaultencoding] + + \setupbodyfont + [palatino,10pt] + + \definefontsynonym[TitleFont][SerifBold] + +\stopnotmode + +\startmode[atpragma] + + \usetypescriptfile[type-ghz] + + \setupfontsynonym [Sans] [handling=quality] + \setupfontsynonym [SansBold] [handling=quality] + \setupfontsynonym [SansSlanted] [handling=quality] + \setupfontsynonym [SansItalic] [handling=quality] + \setupfontsynonym [SansBoldSlanted] [handling=quality] + \setupfontsynonym [SansBoldItalic] [handling=quality] + + %setupfontsynonym [Mono] [handling=quality] % sloooow + + \definetypeface[optima][ss][sans][optima-nova] [default][encoding=\defaultencoding] + \definetypeface[optima][tt][mono][latin-modern][default][encoding=\defaultencoding,rscale=1.1] + + \setupbodyfont[optima,10pt,ss] + + \definefontsynonym[TitleFont][SansBold] + +\stopmode + +%D This document is mildly interactive. Yes, Thanh's name will end up ok in +%D the document information data. + +\setupinteraction + [state=start, + style=normal, + color=, + page=yes, + openaction=firstpage, + title=pdfTeX users manual, + author={H\`an Th\^e Th\`anh, Sebastian Rahtz, Hans Hagen, Hartmut Henkel, + Pawe\l\ Jackowski, Martin Schr\"oder, Karl Berry}] + +\setupinteractionscreen % still needed? + +\startnotmode[screen] + +\setupinteractionscreen + [option=bookmark] + +\stopnotmode + +%D Some headers and footers will complete the layout. + +\setupheadertexts + [The pdf\TeX\ user manual] + +\setupfootertexts + [pagenumber] + +%D For Tobias Burnus, who loves bookmarks, I've enabled them. + +\placebookmarks + [section,subsection,pdftexprimitive] + +%D Let's also define a screen layout: + +\startmode[screen] \environment pdftex-i \stopmode + +%D We auto-cross link the paper and screen version: + +\startnotmode[screen] + +%\coupledocument +% [screenversion] +% [pdftex-s] +% [section,subsection,subsubsection,pdftexprimitive] +% [the screen version] + +\setuphead + [section,subsection,subsubsection,pdftexprimitive] + [file=screenversion] + +\setuplist + [section] + [alternative=c] + +\stopnotmode + +%D The text starts here! + +\starttext + +%D Being lazy, I don't split the file, so paper and screen get +%D mixed in one document. + +\startmode[screen] \getbuffer[screen] \stopmode + +\startnotmode[screen] + +%D But first we typeset the title page. It has a background. This +%D background, showing a piece of \PDF\ code, will be referred to +%D later on. + +%D We can use more modern \CONTEXT\ features, but for the moment +%D stick to the old style and methods. + +\NormalizeFontWidth + \TitleFont + {\hskip.5mm The pdf\TeX\ user manual} % \hskip is fake offset + \paperheight + {TitleFont} + +\setupbackgrounds + [page] + [background={title,joke,names,content}] + +\defineoverlay + [title] + [\hbox to \paperwidth + {\hfill + \TitleFont\setstrut + \rotate{The pdf\TeX\ user manual}% + \hskip.5cm}] % \dp\strutbox}] + +% \defineoverlay +% [joke] +% [\hbox to \paperwidth +% {\TitleFont\setstrut +% \dimen0=\overlaywidth +% \advance\dimen0 by -\ht\strutbox +% \advance\dimen0 by -\dp\strutbox +% \advance\dimen0 by -1cm +% \dimen2=\overlayheight +% \advance\dimen2 by -1cm +% \hskip.5cm\expanded{\externalfigure +% [pdftex-z.pdf] +% [width=\the\dimen0,height=\the\dimen2]}% +% \hfill}] + +% \defineoverlay +% [names] +% [\vbox to \paperheight +% {\dontcomplain +% \TitleFont\setstrut +% \setbox0=\hbox{\TeX}% +% \hsize\paperwidth +% \rightskip\ht0 +% \advance\rightskip\dp\strutbox +% \advance\rightskip\dp\strutbox +% \bfa \setupinterlinespace +% \vfill +% \hfill \THANH \endgraf +% \hfill Sebastian Rahtz \endgraf +% \hfill Hans Hagen +% \hfill Hartmut Henkel +% \hfill Pawe\l\ Jackowski +% \vskip 1ex +% \hfill \currentdate +% \vskip 2ex}] + +\defineoverlay + [content] + [\overlaybutton{contents}] + +% title page + +\definelayout + [titlepage] + [backspace=.5cm, + cutspace=3.5cm, + topspace=.5cm, + bottomspace=.5cm, + header=0pt, + footer=0pt, + lines=\getvariable{pdftex}{titlepagelines}, + grid=yes, + width=middle] + +\definecolumnset + [titlepage] + [n=2,distance=0.2cm] + +\start + + \chardef\fontdigits=2 + \switchtobodyfont[10pt,tt] + \setupinterlinespace + [line=\dimexpr((\paperheight-1cm)/\getvariable{pdftex}{titlepagelines})] + \setuptyping[margin=,color=] + \setuplayout[titlepage] + + \startcolumnset[titlepage] + \typefile{pdftex-w.txt} + \stopcolumnset + + \page + \setuplayout + +\stop + +% \startstandardmakeup +% +% %D The titlepage is generated using the background overlay mechanism. This +% %D saves me the trouble of determining funny skips and alignments. So no text +% %D goes here. +% +% \stopstandardmakeup + +\setupbackgrounds + [page] + [background=] + +%D The inside title page is as follows. + +\startstandardmakeup[footerstate=none] + + \dontcomplain + + \setupalign[left] + + \start + + \bfd The pdf\TeX\ user manual + + \bfa \setupinterlinespace + + \vskip4ex + + \THANH\par + Sebastian Rahtz\par + Hans Hagen\par + Hartmut Henkel\par + Pawe\l\ Jackowski\par + Martin Schr\"oder\par + + \vskip3ex + + \rcsmonthname\ \rcsday, \rcsyear\par + \vskip1ex + Rev.\ \rcsrevision + + \stop + + \vfill + + \startlines + The title page is the result of + this plain \TeX\ text: + \stoplines + + \blank[2*big] \setuptyping[after=] + + \starttyping + \pdfoutput=1 + \pdfcompresslevel=0 + \pdfobjcompresslevel=0 + \pdfmapline{ptmr8r Times-Roman 2 <8r.enc} + \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 standard \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). + +\PDFTEX\ is based on the original \TEX\ sources and \WEBC, and has been +successfully compiled on \UNIX, \WIN\ and \MSDOS\ systems. It is +actively maintained, 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 {conservative} successor to \TEX\ +available, called \ETEX. Because mainstream macro packages such as +\LATEX\ have started supporting this welcome extension, the \ETEX\ +functionality has also been integrated into the \PDFTEX\ code. For a +while (\TEXLIVE~2004 and~2005) \PDFTEX\ therefore came in two flavours: +the \ETEX\ enabled \PDFETEX\ engine and the standard one, \PDFTEX. The +ability to produce both \PDF\ and \DVI\ output made \PDFETEX\ the +primary \TEX\ engine in these distributions. Since \PDFTEX\ version 1.40 +now the \ETEX\ extensions are part already of the \PDFTEX\ engine, so +there is no longer any need to ship \PDFETEX. The \ETEX\ functionality +of \PDFTEX\ can be disabled if not required. Other extensions are +\MLTEX\ and \ENCTEX; these are also included in the current \PDFTEX\ +code. + +\PDFTEX\ is maintained by \THANH, Martin Schr\"oder, and others. The +\PDFTEX\ homepage is \from [ptex_org]. Please send \PDFTEX\ comments and +bug reports to the mailing list \from [ptex_bugs] (\from [ptex_listinfo]). + +%*********************************************************************** + +\subsection{About this manual} + +This manual revision (\rcsrevision) is intended to cover +\PDFTEX\ development up to version \currentpdftex. The primary +repository for the manual and its sources is at \from[ptex_devel]. +Copies in \PDF\ format can also be found on \CTAN\ via \from[ptex_ctan]. + +Thanks to the many people who have contributed to the manual. +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||2017 \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, from the corresponding source on the next page. Since +compression is not enabled, such a \PDF\ file is rather verbose and +readable. The first line specifies the version used. \PDF\ viewers are +supposed to silently skip over all elements they cannot handle. + +A \PDF\ file consists of objects. These objects can be recognized by their +number and keywords: + +\starttyping +9 0 obj << /Type /Catalog /Pages 5 0 R >> endobj +\stoptyping + +Here \typ{9 0 obj ... endobj} is the object capsule. The first number +is the object number. The sequence \type{5 0 R} is an object reference, +a pointer to another object (no.~5). The second number (here a zero) +is currently not used in \PDFTEX; it is the version number of the +object. It is for instance used by \PDF\ editors, when they replace +objects by new ones. + +When a viewer opens a \PDF\ file, it goes to the end of the file, +looking for the keyword \type{startxref}. The number after +\type{startxref} gives the absolute position (byte offset from the file +start) of the so||called \quote {object cross-reference table} that +begins with the keyword \type{xref}. This table in turn tells the byte +offsets of all objects that make up the \PDF\ file, providing fast +random access to the individual objects (here the \type{xref} table +shows 11~objects, numbered from~0 to~10; the object no.~0 is always +unused). The actual starting point of the file's object structure is +defined after the \type{trailer}: the \type{/Root} entry points to the +\type{/Catalog} object (no.~9). In this object the viewer can find the +pointer \type{/Pages} to the page list object (no.~5). In our example we +have only one page. The trailer also holds an \type{/Info} entry, which +points to an object (no.~10) with a bit more about the document. Just +follow the thread: + +\startnarrower +\type{/Root} $\longrightarrow$ object~9 $\longrightarrow$ +\type{/Pages} $\longrightarrow$ object~5 $\longrightarrow$ +\type{/Kids} $\longrightarrow$ object~2 $\longrightarrow$ +\type{/Contents} $\longrightarrow$ object~3 +\stopnarrower + +As soon as we add annotations, a fancy word for hyperlinks and the like, +some more entries will be present in the catalog. We invite users to +take a look at the \PDF\ code of this file to get an impression of that. + +The page content is a stream of drawing operations. Such a stream +can be compressed, where the level of compression can be set with +\type{\pdfcompresslevel} (compression is switched off for the title +page). Let's take a closer look at this stream in object~3. Often +(but not in our example) there is a transformation matrix, six numbers +followed by \type{cm}. As in \POSTSCRIPT, the operator comes after the +operands. Between \type{BT} and \type{ET} comes the text. A font is +selected by a \type{Tf} operator, which is given a font resource name +\type{/F..} and the font size. The actual text goes into \type{()} +bracket pairs so that it creates a \POSTSCRIPT\ string. The numbers +in bracket pairs provide horizontal movements like spaces and +fine glyph positioning (kerning). When one analyzes a file produced by +a less sophisticated typesetting engine, whole sequences of words can +be recognized. In \PDF\ files generated by \PDFTEX\ however, many words +come out rather fragmented, mainly because a lot of kerning takes place; +in our example the \type{80} moves the text \type{(elcome)} left towards +the letter \type{(W)} by 80/1000 of the font size. \PDF\ viewers in search +mode simply ignore the kerning information in these text streams. When +a document is searched, the search engine reconstructs the text from these +(string) snippets. + +Every \type{/Page} object points also to a \type{/Resources} object +(no.~1) that gives all ingredients needed to assemble the page. In our +example only a \type{/Font} object (no.~4) is referenced, which in turn +tells that the text is typeset in \type{/Font} \type{/Times-Roman}. The +\type{/Font} object points also to a \type{/Widths} array (object no.~7) +that tells for each character by how much the viewer must move forward +horizontally after typesetting a glyph. More details about the font +can be found in the \type{/FontDescriptor} object (no.~8); if a font +file is embedded, this object points to the font program stream. But as +the Times-Roman font used for our example is one of the 14 so||called +standard fonts that should always be present in any \PDF\ viewer and +therefore need not be embedded in the \PDF\ file, it is left out here +for brevity. However, when we use for instance a Computer Modern Roman +font, we have to make sure that this font is later available to the \PDF\ +viewer, and the best way to do this is to embed the font. +It's highly recommended nowadays to embed even the standard fonts; +you can't know how it looks exactly at the viewer side unless you embed +every font. + +In this simple file we don't specify in what way the file should be opened, +for instance full screen or clipped. A closer look at the page object no.~2 +(\typ{/Type /Page}) shows that a mediabox (\typ{/MediaBox}) is part of the +page description. A mediabox acts like the (high-resolution) bounding box +in a \POSTSCRIPT\ file. \PDFTEX\ users can add dictionary entries to page +objects with the \type{\pdfpageattr} primitive. + +Although in most cases macro packages will shield users from these +internals, \PDFTEX\ provides access to many of the entries described +here, either automatically by translating the \TEX\ data structures into +\PDF\ ones, or manually by pushing entries to the catalog, page, info or +self-created objects. One can for instance create an object by using +\type{\pdfobj}, after which \type{\pdflastobj} returns its number. So + +\starttyping +\pdfobj{<< /Type/ExtGState /LW 2 >>} +\stoptyping + +inserts an object into the \PDF\ file (it creates a ``graphics state'' +object setting the line width to 2~units), and \type{\pdflastobj} now +returns the number \PDFTEX\ assigned to this object. Unless objects are +referenced by others, they will just end up as isolated entities, not +doing any real harm but bloating the \PDF\ file. + +In general this rather direct way of pushing objects in the \PDF\ files +by primitives like \type{\pdfobj} is not very useful, and only makes +sense when implementing, say, fill||in field support or annotation +content reuse. We will come to that later. + +Of course, this is just the barest introduction to \PDF\ format. For +those who want to learn more about the gory \PDF\ details, the best bet +is to read the \PDFReference. You can download this book as a big \PDF\ +file from Adobe's \PDF\ Technology Center, \from[pdfreference] --- or +get the heavy paper version. + +We now turn to specifics of \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, +\MIKTEX, \TETEX, \XEMTEX, \PROTEXT, and \MACTEX. The ready to run +\TEXLIVE\ distribution comes with \PDFTEX\ versions for many \UNIX, +\WIN, and \MACOSX\ systems; more information can be found at +\hbox{\from[texlive].} There are also \WIN-specific distributions which +contain \PDFTEX, under \from[win32]: \MIKTEX\ by Christian Schenk, and +\PROTEXT\ (based on \MIKTEX) by Thomas Feuerstack. When you use any +of these distributions, you don't need to bother with the \PDFTEX\ +installation procedure in the next sections. + +If there is no precompiled \PDFTEX\ binary for your system, or the version +coming with a distribution is not the current one and you would like to +try out a fresh \PDFTEX\ immediately, you will need to build \PDFTEX\ +from sources; read on. You should already have a working \TEX\ system, +\eg\ \TEXLIVE\ or \TETEX, into which the freshly compiled \PDFTEX\ will +be integrated. Note that the installation description in this manual +is \WEBC||specific. + +%*********************************************************************** + +\subsection{Getting sources and binaries} + +The latest sources of \PDFTEX\ are distributed for compilation on \UNIX\ +systems (including \GNU/Linux), and \WIN\ systems. The primary home +page is \from[ptex_org], where you also find bug tracking information. +Development sources are at \from[ptex_devel]. Precompiled \PDFTEX\ +binaries for various systems might be available in subdirectories below +\from[ctan_systems], or via \TEX\ distribution web pages. + +%*********************************************************************** + +\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 pdftex.../source +./build-pdftex.sh +\stopesctyping + +The binary \filename{pdftex} is then built in the subdirectory +\filename{build/texk/web2c}. + +The obsolescent binary \filename{pdfetex} is still generated for backward +compatibility, but since version 1.40 it is just a file copy +of the file \filename{pdftex}. + +As well as the main \filename{pdftex} binary, binaries for the utilities +\filename{pdftosrc} and \filename{ttf2afm} are generated. + +Incidentally, for \PDFTEX\ maintains, a sibling script to +\type{build-pdftex.sh} is included, namely \type{sync-pdftex.sh}, which +syncs changes from a \TEXLIVE\ source repository to a \PDFTEX\ source +repository. Read the script before using it. And don't use it unless +you understand what you read. + +%*********************************************************************** + +\subsection{Placing files} + +The next step is to put the freshly compiled \filename{pdftex}, +\filename{pdftosrc}, and \filename{ttf2afm} binaries into the binary +directory (\eg\ for a typical \TEXLIVE\ system, and on the appropriate +platform) \filename{/usr/local/texlive/\rcsyear/bin/x86_64-linux}. + +If you're doing this into a live hierarchy, don't forget to do a +\type{texconfig-sys init} afterwards, so that all formats are +regenerated system-wide with the fresh \filename{pdftex} binary. + +%*********************************************************************** + +\subsection{Setting search paths} + +\WEBC||based programs, including \PDFTEX, use the \WEBC\ run||time +configuration file called \filename {texmf.cnf}. The location +of this file is the appropriate position within the \TDS\ tree +relative to the place of the \PDFTEX\ binary; on a \TEXLIVE\ system, +\filename{texmf.cnf} is typically 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}. + +The \filename{texmf.cnf} files coming with the major \TEX\ distributions +should already be set up for normal use, so you shouldn't need to edit +it. You might still like to read it to see where the various bits and +pieces are going. + +\PDFTEX\ uses the search path variables shown in +\in{table}[tbl:spathvar], among others. + +\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 \TeX\ 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 Type~1 fonts \NC \type{T1FONTS} \NC\NR +\NC TrueType fonts \NC \type{TTFONTS} \NC\NR +\NC OpenType fonts \NC \type{OPENTYPEFONTS} \NC\NR +\NC bitmap fonts \NC \type{PKFONTS} \NC\NR +\HL +\stoptabulate +\stopbuffer + +\placetable[here][tbl:spathvar] + {The principal \WEBC\ variables.} + {\getbuffer} + +\PathDescription {TEXMFOUTPUT} Normally, \PDFTEX\ puts its output files +in the current directory, overridden by the \type{-output-directory} +option. If any output file cannot be opened there, it tries to open it +in the environment variable \type{TEXMFOUTPUT}, if that is set. There is +no default value for that variable. For example, if \type{TEXMFOUTPUT} +has the value \type{/tmp}, and you run \type{pdftex paper} when the +current directory is not writable, \PDFTEX\ attempts to create +\type{/tmp/paper.log} (and \type{/tmp/paper.pdf}, etc.) + +\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; no +longer used, since the pool file (program strings) are compiled into +the binary. + +\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 {TTFONTS,\hfil\break \hbox{OPENTYPEFONTS}} Search paths +for TrueType (\type{.ttf}) and OpenType (\type{.otf}) font files. Like +Type~1 fonts, TrueType and OpenType fonts are also outlines. + +\PathDescription {PKFONTS} Search path for packed (bitmap) font +(\type{.pk}) files. +Unfortunately bitmap fonts are still displayed poorly by some \PDF\ +viewers, so when possible one should use outline fonts. When no outline +is available, \PDFTEX\ tries to locate a suitable \PK\ font (or invoke +a process that generates it). + +\PathDescription{TEXFONTS} Fallback for all the font paths, so that if +you want to look in a particular directory for fonts on a given run, you +can set that one variable. + +Many more variables may be consulted, and there are many details to +file name lookups. See the Kpathsea manual (\from [kpathsea]). + +%*********************************************************************** + +\subsection[cfg]{The \PDFTEX\ configuration} + +We must keep in mind that, as opposed to \TEX\ with its \DVI\ output, +the \PDFTEX\ program does not have a separate postprocessing stage to +transform the \TEX\ input into final \PDF. 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 to setting up the \PDFTEX\ engine +is given in \in{table}[tbl:configparms]. All primitives are described in +detail within later sections. \in{Figure}[in:pdftexconfig] shows a recent +configuration file (\type{pdftexconfig.tex}) in \TEX\ format, using the +primitives from \in{table}[tbl:configparms], which typically is read +in during the format building process. It enables \PDF\ output, sets paper +dimensions and the default pixel density for \PK\ font inclusion. The default +values are chosen so that \PDFTEX\ often can be used (\eg\ in \type{-ini} mode) +even without setting any parameters. + +\startbuffer +\starttabulate[|l|l|l|l|l|] +\HL +\NC \bf internal name \NC \bf type \NC\bf default\NC\bf comment\NC\NR +\HL +\NC \type{\pdfoutput} \NC integer \NC 0 \NC \DVI \NC\NR +\NC \type{\pdfadjustspacing} \NC integer \NC 0 \NC off \NC\NR +\NC \type{\pdfcompresslevel} \NC integer \NC 9 \NC best \NC\NR +\NC \type{\pdfobjcompresslevel} \NC integer \NC 0 \NC no object streams \NC\NR +\NC \type{\pdfdecimaldigits} \NC integer \NC 4 \NC max. \NC\NR +\NC \type{\pdfimageresolution} \NC integer \NC 72 \NC dpi \NC\NR +\NC \type{\pdfpkresolution} \NC integer \NC 0 \NC 72\,dpi \NC\NR +\NC \type{\pdfpkmode} \NC token reg.\NC empty \NC mode set in \type{mktex.cnf} \NC\NR +\NC \type{\pdfuniqueresname} \NC integer \NC 0 \NC \NC\NR +\NC \type{\pdfprotrudechars} \NC integer \NC 0 \NC \NC\NR +\NC \type{\pdfgentounicode} \NC integer \NC 0 \NC \NC\NR +\NC \type{\pdfminorversion} \NC integer \NC 4 \NC \PDF\ 1.4 \NC\NR +\NC \type{\pdfpagebox} \NC integer \NC 0 \NC \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{\pdffirstlineheight} \NC dimention \NC -1000\,pt \NC \NC\NR +%\NC \type{\pdflastlinedepth} \NC dimention \NC -1000\,pt \NC \NC\NR +%\NC \type{\pdfeachlineheight} \NC dimention \NC -1000\,pt \NC \NC\NR +%\NC \type{\pdfeachlinedepth} \NC dimention \NC -1000\,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 +% tex-ini-files 2016-04-15: pdftexconfig.tex + +% Load shared (PDF) settings in pdfTeX + +% Enable PDF output +\pdfoutput = 1 + +% Paper size: dimensions given in absolute terms +\pdfpageheight = 11 true in +\pdfpagewidth = 8.5 true in + +% Enable PDF 1.5 output and thus more compression +\pdfminorversion = 5 +\pdfobjcompresslevel = 2 + +% Low-level settings unlikely ever to need to change +\pdfcompresslevel = 9 +\pdfdecimaldigits = 3 +\pdfpkresolution = 600 +\pdfhorigin = 1 true in +\pdfvorigin = 1 true in +\stoptyping +\stopframedtext +\stopbuffer + +\placefigure[here][in:pdftexconfig] + {\PDFTEX\ configuration file for \TEXLIVE\ (\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 \WEBC\ system. This file mainly defines file search paths, the +memory layout (\eg\ string pool and hash size), and other general parameters. + +%*********************************************************************** + +\subsection{Creating format files} + +\startbuffer +\tx\setupinterlinespace +\startframedtext +\starttyping +% Thomas Esser, 1998. public domain. +\input etex.src +\dump +\endinput +\stoptyping +\stopframedtext +\stopbuffer + +\placefigure[here][in:etexini] + {File \type{etex.ini} for the plain \ETEX\ format with \DVI\ output.} + {\getbuffer} + +\startbuffer +\tx\setupinterlinespace +\startframedtext +\starttyping +% Thomas Esser, 1998. public domain. +% This is used for pdftex and pdfetex, which are now identical: both +% with e-TeX extensions, both with pdf output. +\input pdftexconfig.tex +\input etex.src +\input pdftexmagfix.tex +\dump +\endinput +\stoptyping +\stopframedtext +\stopbuffer + +\placefigure[here][in:pdfetexini] + {File \type{pdfetex.ini} for plain \ETEX\ with \PDF\ output.} + {\getbuffer} + +\startbuffer +\tx\setupinterlinespace +\startframedtext +\starttyping +% Thomas Esser, 1998. public domain. +\input pdftexconfig.tex +\scrollmode +\input latex.ltx +\endinput +\stoptyping +\stopframedtext +\stopbuffer + +\placefigure[here][in:pdflatexini] + {File \type{pdflatex.ini} for the \LATEX\ format with \PDF\ output.} + {\getbuffer} + +The \PDFTEX\ engine supports 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 invocation of \PDFTEX\ with this format starts in the +preselected mode (which still can be overridden). A format file can be +read in only by the engine that has generated it; a format incompatible +with an engine leads to a fatal error. + +It is customary to package the configuration and macro file input +into a \type{.ini} file. \Eg, the file \type{etex.ini} in +\in{figure}[in:etexini] is for generating an \ETEX\ format with \DVI\ +output. It has been traditional for many years to generate +\type{etex.fmt} with \PDFTEX\ rather than the original \ETEX, because +\PDFTEX\ contains a few additional programming and other +non-\PDF-related features on which people have come to rely. + +The \type{pdfetex.ini} file \in{figure}[in:etexini] shows the +corresponding format with \PDF\ output by default; this is what creates +the format file read when \type{pdftex} is normally invoked. + +Finally, \type{pdflatex.ini} \in{figure}[in:pdflatexini] shows how the +\LATEX\ format with \PDF\ output by default is generated. + +The corresponding \PDFTEX\ calls for format generation are: + +\starttyping +pdftex -ini *etex.ini +pdftex -ini *pdfetex.ini +pdftex -ini *pdflatex.ini +\stoptyping + +These calls produce format files \filename{etex.fmt}, +\filename{pdfetex.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{*} before the +file name is a unusual feature, only in \type{-ini} mode, which causes +the \PDFTEX\ engine to enable \ETEX\ features. + +\subsection{Testing the installation} + +When everything is set up, you can test the installation. A simple test +of plain \PDFTEX\ is: + +\starttyping +pdftex story \\end +\stoptyping + +This should typeset the famous one-page short story by A.U. Thor. + +A more thorough and descriptive test is the plain \TEX\ test file +\filename{samplepdf.tex}, available in the distribution in the +\type{samplepdftex/} directory. Process this file by typing: + +\starttyping +pdftex samplepdf +\stoptyping + +If the installation is ok, this should produce a file called +\filename{samplepdf.pdf}. The file \filename {samplepdf.tex} is a good +place to look for examples of 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 use the option +\type{-kpathsea-debug 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 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{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. + The first line tells by which engine the offending format was generated. + +\head \PDFTEX\ cannot find one or more map files (\type{*.map}), + encoding vectors (\type{*.enc}), virtual fonts, Type~1 fonts, + TrueType or OpenType fonts, or some image file. + + Make sure that the required file exists and the corresponding variable + in \filename {texmf.cnf} contains a path to the file. See above which + variables \PDFTEX\ needs apart from the ones \TEX\ uses. + + When you have installed new fonts, and your \PDF\ viewer complains + about missing fonts, you should take a look at the log file produced + by \PDFTEX. Missing fonts, map files, encoding vectors as well as + missing characters (glyphs) are reported there. + +\stopitemize + +Normally the page content takes one object. This means that one seldom +finds more than a few hundred objects in a simple file. This \PDFTEX\ +manual for instance uses approx.~750 objects. In more complex applications +this number can grow quite rapidly, especially when one uses a lot of +widget annotations, shared annotations or other shared things. In any +case \PDFTEX's internal object table size will automatically grow to the +required size (the parameter \type{obj_tab_size} for manual control of +the object table size is now obsolete and ignored). + +%*********************************************************************** + +\section{Invoking \PDFTEX} + +\PDFTEX\ has many command line options. With the exception of the +simple and rarely-used \type{-draftmode} and \type{-output-format} +options, they are all inherited from the common framework for \TeX\ +engines as implemented in \WEBC\ (\from [web2c] has the manual). + +The same commonality holds for environment variables; see the section +``Setting search paths'' above for an overview. Two additional +environment variables need more description here: first, +\type{SOURCE_DATE_EPOCH} (introduced in version 1.40.17, 2016). If this +is set, it must be a positive integer (with one trivial exception: if it +is set but empty, that is equivalent to 0). Non-integer values cause a +fatal error. The value is used as the current time in seconds since the +usual Unix ``epoch'': the beginning of 1970-01-01, UTC. Thus, a value +of \type{32} would result in a \type{/CreationDate} and \type{/ModDate} +values of \type{19700101000032Z}. This is useful for reproducible +builds of documents. (See also \type{\pdfinfoomitdate}, +\type{\pdfsuppressptexinfo}, et al.) + +The second, related, environment variable is \type{FORCE_SOURCE_DATE}. +If this is set to~\type{1}, \TEX's time-related primitives are also +initialized from the value of \type{SOURCE_DATE_EPOCH}. These +primitives are \type{\year}, \type{\month}, \type{\day}, and +\type{\time}. If \type{SOURCE_DATE_EPOCH} is not set, setting +\type{FORCE_SOURCE_DATE} has no effect. If \type{FORCE_SOURCE_DATE} is +unset, set to the empty string, or set to~\type{0}, the primitives +reflect the current time as usual. Any other value elicits a warning, +and the current time is used. (This is useful only if one wants to make +reproducible \PDF{}s for a set of documents without changing them in any +way, e.g., an operating system distribution with manuals that use +\type{\today}. Except in such unusual circumstances, it is better not +to set this, and let the \TEX\ primitives retain the meaning they have +always had.) + +Finally, just to have the list of options and basic invocation at hand, +here is a verbatim listing of the \type{-}\type{-help} output. All +options can be specified with one or two dashes and unambiguously +abbreviated. + +\startnotmode[screen] + \switchtobodyfont[9pt] % squeeze everything on one page +\stopnotmode + +\typefile{pdftex-help.txt} + +\startnotmode[screen] + \switchtobodyfont[10pt] % squeeze everything on one page +\stopnotmode + +%*********************************************************************** + +\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 +controlled 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 + \hbox{\tt -{}-pdf} option. + +\item \PDF\ from \TEXINFO\ documents can be created by running \PDFTEX\ on + the \TEXINFO\ file, instead of \TEX. Alternatively, run the shell + command \type{texi2pdf} instead of \type{texi2dvi}. + +\item A small modification of \filename {webmac.tex}, called \filename + {pdfwebmac.tex}, allows production of hyperlinked \PDF\ versions + of the program code written in \WEB. + +\stopitemize + +Some nice samples of \PDFTEX\ output can be found at +\from[ptex_org], \from[context], and \from[tex_showcase]. + +%*********************************************************************** + +\section{Setting up fonts} + +\PDFTEX\ can work with Type~1 and TrueType fonts (and to some extent +also with OpenType fonts). Font files should be available and embedded +for all fonts used in the generated PDF. 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 +poorly under enlargement. + +%*********************************************************************** + +\subsection[mapfile]{Map files} + +Font map files provide the connection between \TEX\ \TFM\ font files +and outline font file names. They contain also information about +re||encoding arrays, partial font embedding (``subsetting''), and +character transformation parameters (like SlantFont and ExtendFont). Those +map files were first created for \DVI\ postprocessors. But, as \PDFTEX\ +in \PDF\ output mode includes all \PDF\ processing steps, it also needs +to know about font mapping, and therefore reads in one or more map files. +Map files are not read in when \PDFTEX\ is in \DVI\ mode. Bitmap fonts +can (and normally should) 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 a single 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 psname fontflags special encodingfile fontfile} +\stopnarrower + +It is mandatory that {\em tfmname} is the first field. If a {\em +psname} is given, it must be the second field. Similarly if {\em +fontflags} is given it must be the third field (if {\em psname} is +present) or the second field (if {\em psname} is left out). The +positions of {\em special}, {\em encodingfile}, and {\em fontfile} can +be mixed. + +\startdescription {tfmname} +sets the name of the \TFM\ file for a font --- the file name given in a +\TEX\ \type{\font} command. This name must always be given. + +\stopdescription + +\startdescription {psname} +sets the (\POSTSCRIPT) base font name, which has two uses: + +First, when a \PDF\ file is embedded by \type{\pdfximage}, the +\type{/BaseFont} names in the font dictionaries of Type~1 and Type~1C +(CFF) fonts from the embedded \PDF\ file are checked against this {\em +psname} field. If names match, the glyphs of that font will not be +copied from the embedded \PDF\ file, but instead a local font is opened, +and all needed glyphs will be taken from the Type~1 font file that is +mentioned in the map line (see {\em fontfile} below). By this collecting +mechanism Type~1 glyphs can be shared between several embedded \PDF\ +files and with text that is typeset by \PDFTEX, which helps keeping the +resulting \PDF\ file size small, if many files with similar Type~1(C) +fonts are embedded. Replacing Type~1 fonts from embedded \PDF\ files +requires that also a Type~1 font file name is in the {\em fontfile} field +(see below). + +Second, if a font file is not to be embedded into the \PDF\ output +({\em fontfile} field missing), then the {\em psname} field will be +copied to the \type{/BaseFont} and \type{/FontName} dictionary entries +in the \PDF\ file, so that the \POSTSCRIPT\ font name will be known to +reading applications (\eg\ viewers). + +It is highly recommended to use the {\em psname} field, but +strictly speaking it is optional. + +\stopdescription + +\startdescription {fontflags} +optionally specify some characteristics of the font. The following description of +these flags is taken, with slight modification, from the \PDFReference\ +(the section on font descriptor flags). Viewers can adapt their rendering +to these flags, especially when they substitute a non-embedded font by +some own approximation. + +\startnarrower + +The value of the flags key in a font descriptor is a 32||bit integer that +contains a collection of boolean attributes. These attributes are true if the +corresponding bit is set to~1. \in{Table}[flags] specifies the meanings of +the bits, with bit~1 being the least significant. Reserved bits must be set +to zero. + +\startbuffer +\starttabulate[|c|l|] +\HL +\NC \bf bit position \NC \bf semantics \NC\NR +\HL +\NC 1 \NC Fixed||width font \NC\NR +\NC 2 \NC Serif font \NC\NR +\NC 3 \NC Symbolic font \NC\NR +\NC 4 \NC Script font \NC\NR +\NC 5 \NC Reserved \NC\NR +\NC 6 \NC Uses the Adobe Standard Roman Character Set \NC\NR +\NC 7 \NC Italic \NC\NR +\NC 8--16 \NC Reserved \NC\NR +\NC 17 \NC All||cap font \NC\NR +\NC 18 \NC Small||cap font \NC\NR +\NC 19 \NC Force bold at small text sizes \NC\NR +\NC 20--32 \NC Reserved \NC\NR +\HL +\stoptabulate +\stopbuffer + +\placetable + [here][flags] + {The meaning of flags in the font descriptor.} + {\getbuffer} + +All characters in a {\em fixed||width} font have the same width, while +characters in a proportional font have different widths. Characters in a {\em +serif font} have short strokes drawn at an angle on the top and bottom of +character stems, while sans serif fonts do not have such strokes. A {\em +symbolic font} contains symbols rather than letters and numbers. Characters +in a {\em script font} resemble cursive handwriting. An {\em all||cap} font, +which is typically used for display purposes such as titles or headlines, +contains no lowercase letters. It differs from a {\em small||cap} font in +that characters in the latter, while also capital letters, have been sized +and their proportions adjusted so that they have the same size and stroke +weight as lowercase characters in the same typeface family. + +Bit~6 in the flags field indicates that the font's character set +conforms to the +Adobe Standard Roman Character Set, or a subset of that, and that it uses +the standard names for those characters. + +Finally, bit~19 is used to determine whether or not bold characters are +drawn with extra pixels even at very small text sizes. Typically, when +characters are drawn at small sizes on very low resolution devices such +as display screens, features of bold characters may appear only one pixel +wide. Because this is the minimum feature width on a pixel||based device, +ordinary non||bold characters also appear with one||pixel wide features, +and thus cannot be distinguished from bold characters. If bit~19 is set, +features of bold characters may be thickened at small text sizes. + +\stopnarrower + +If the {\em fontflags} field is not given, and the font is embedded, +\PDFTEX\ treats it as the value~4 (decimal, that is, bit position 3 is set), +a symbolic font. For non-embedded fonts, the default value is +\type{0x22}, a non-symbolic serif 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 trouble 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} +specifies font manipulations in the same way as +\type{dvips}. Currently only the keywords \type{SlantFont} +and \type{ExtendFont} are interpreted, other instructions (notably +\type{ReEncodeFont} and its 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 quote characters: \type{"}. + +\stopdescription + +\startdescription {encodingfile} specifies the name of the file +containing the external encoding vector to be used for the font. The +encoding file name must have the extension \type{.enc}, and the file +name including extension must be given with either a preceding~\type{<} +character or a preceding~\type{<[}. The format of the encoding vector is +identical to that used by \type{dvips}. If no encoding is specified, the +font's built||in default encoding is used. The {\em encodingfile} field +may be omitted if you are sure that the font resource has the correct +built||in encoding. In general this option is highly recommended, and it +is {\em required} when subsetting a TrueType font. + +Starting with version 1.40.19, an encoding file can also be specified +for bitmap \PK\ fonts. In this case, it assigns the glyph names from the +given encoding vector, which can be used with the +\type{\pdfglyphtounicode} primitive (q.v.). For example: + +\starttyping +\pdfglyphtounicode{ffi}{0066 0066 0069} % normally: \input glyphtounicode +\pdfgentounicode=1 +\pdfmapline{cmb10 <7t.enc} +\font\cmb=cmb10 \cmb ffi +\stoptyping + +The result is a \PDF\ file with a correctly-labeled \type{/ffi} +character instead of the numeric character position in the +\type{cmb10.tfm} (decimal 14). + +\stopdescription + +\startdescription {fontfile} +sets the name of the font file to be embedded into the \PDF\ output for a +given \TeX\ font (the {\em tfmname}~$\leftrightarrow$~{\em fontfile} +mapping is the most prominent use of the \filename{pdftex.map} file). +The font file name must belong to a Type~1 or TrueType font file. If +the {\em fontfile} field is missing, no font embedding can take place; +in case the {\em psname} field does not contain one of the 14 standard +font names also a warning will be given. Not embedding a font into a \PDF\ +file might be troublesome, as it requires that the font or some similar +looking replacement font is available within the \PDF\ viewer, so that +it can render the glyphs with its own font version. + +The font file name should be preceded by one or two special characters, +specifying how to handle the font file: + +\startitemize + +\item If the font file name is preceded by a \type{<} character, the + font file will be only partially embedded in the \PDF\ output + (``subsetted''), meaning that only used glyphs are written to + the \PDF\ file. This is the most common use and is {\em strongly + recommended} for any font, as it ensures the portability and + reduces the size of the \PDF\ output. Subsetted fonts are included + in such a way that name and cache clashes are minimized. + +\item If the font file name is preceded by a double \type{<<}, the font + file will be included entirely --- all glyphs of the font are + embedded, including even those not used in the document. Apart + from causing large size \PDF\ output, this option may cause + troubles with TrueType fonts, so it is normally not recommended + for Type~1 or TrueType fonts. But this is currently the only mode + that allows the use of OpenType fonts. This mode might also be + useful in case the font is atypical and cannot be subsetted well + by \PDFTEX. {\em Beware: proprietary font vendors typically + forbid full font inclusion.} + +\item If no special character precedes the font file name, it is + ignored, with a warning (this case was deprecated in \PDFTEX\ + version 1.40.0). You achieve exactly the same \PDF\ result if you + just remove the font file name from the map entry. Then the glyph + widths that go into the \PDF~file are extracted from the + \TFM~file, and a font descriptor object is created that contains + approximations of the font metrics for the selected font. + +\item Specifying the {\em psname} and no font file name is only useful + as a last-ditch fallback when you do not want to embed the font + (\eg\ due to font license restrictions), but wish to use the font + metrics and let the \PDF\ viewer generate instances that look + close to the used font in case the font resource is not installed + on the system where the \PDF\ output will be viewed or + printed. To use this feature, the font flags {\em must} be + specified, and it must have the bit~6 set on, which means that + only fonts with the Adobe Standard Roman Character Set can be + simulated. The only exception is the case of a symbolic font, + which is not very useful. + +\stopitemize + +If you encounter problematic lookups, for instance if \PDFTEX\ tries +to open a \type{.pfa} file instead of a \type{.pfb}, you can add +the suffix to the filename. In this respect, \PDFTEX\ completely relies +on the \type{kpathsea} library. + +\stopdescription + +For Type~1 and TrueType fonts, the font file will be included only once +in the \PDF\ output, regardless of how many \TeX\ \type{\font} instances +are used in the document. For instance, given + +\starttyping +\font\a = cmr12 +\font\b = cmr12 at 11pt +\stoptyping + +the outline file \type{cmr12.pfb} will only be included once in the +\PDF, and merely scaled down to create the instance for \type{\b}. + +If a used font is not present in the map files, \PDFTEX\ will try to use +\PK~fonts as most \DVI\ drivers do, creating \PK~fonts on||the||fly if +needed. This is the normal, and recommended, way to use bitmap fonts. + +To summarize this rather confusing story, we include some example map +lines. The most common way is to embed only a subset of glyphs from a +font for a particular desired encoding, like this: + +\starttyping +ptmri8r Times-Italic <8r.enc <ptmri8a.pfb +\stoptyping + +Without re||encoding it looks like this: + +\starttyping +cmr10 CMR10 <cmr10.pfb +\stoptyping + +\type{SlantFont} and \type{ExtendFont} fields are specified as with +\type{dvips}. \type{SlantFont} and \type{ExtendFont} work only with +embedded Type~1 fonts: + +\starttyping +psyro StandardSymL ".167 SlantFont" <usyr.pfb +pcrr8rn Courier ".85 ExtendFont" <8r.enc <pcrr8a.pfb +\stoptyping + +Entirely embed a font into the \PDF\ file without and with re||encoding +(not typically useful): + +\starttyping +fmvr8x MarVoSym <<marvosym.pfb +pgsr8r GillSans <8r.enc <<pgsr8a.pfb +\stoptyping + +A TrueType font can be used in the same way as a Type~1 font: + +\starttyping +verdana8r Verdana <8r.enc <verdana.ttf +\stoptyping + +Finally, a few cases with non-embedded fonts. If the fontfile is +missing, the viewer application will have to use its own approximation +of the missing font (with and without re||encoding): + +\starttyping +ptmr8r Times-Roman <8r.enc +psyr Symbol +\stoptyping + +In the next example the numerical font flags give some rough hint what +general characteristics the GillSans font has, so \eg\ the Adobe Reader +might try an approximation, if it doesn't have the font resource nor +any clue how a font named GillSans should look like: + +\starttyping +pgsr8r GillSans 32 <8r.enc +\stoptyping + +Not embedding fonts is rather risky and should generally be avoided. +The recommendation these days is to embed all fonts, even the 14 standard ones. + +%*********************************************************************** + +\subsection{Helper tools for TrueType fonts} + +As mentioned above, \PDFTEX\ can work with TrueType fonts. Defining +TrueType fonts is similar to Type~1. The only extra thing to do +with TrueType is to create a \TFM\ file. There is a program called +\type{ttf2afm} in the \PDFTEX\ distribution which can be used to +extract \AFM\ from TrueType fonts (another conversion program is +\type{ttf2pt1}). Usage of \type{ttf2afm} is simple: + +\starttyping +ttf2afm -e <encoding vector> -o <afm outputfile> <ttf input file> +\stoptyping + +A TrueType file can be recognized by its suffix \filename {ttf}. The optional +{\em encoding} specifies the encoding, which is the same as the encoding +vector used in map files for \PDFTEX\ and \type{dvips}. If the encoding is +not given, all the glyphs of the \AFM\ output will be mapped to \type +{/.notdef}. \type{ttf2afm} writes the output \AFM\ to standard output. If we +need to know which glyphs are available in the font, we can run \type +{ttf2afm} without encoding to get all glyph names. The resulting \AFM\ file +can be used to generate a \TFM\ one by applying \filename {afm2tfm}. + +To use a new TrueType font the minimal steps may look like below. We suppose +that \filename {test.map} is used. + +\starttyping +ttf2afm -e 8r.enc -o times.afm times.ttf +afm2tfm times.afm -T 8r.enc +echo "times TimesNewRomanPSMT <8r.enc <times.ttf" >>test.map +\stoptyping + +There are a few limitations with TrueType fonts in comparison with +Type~1 fonts: + +\startitemize[a,packed] +\item The special effects SlantFont|/|ExtendFont did not work + before version 1.40.0. +\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 + +For much more about \PDFTEX\ and TrueType fonts, including many details +on handling glyph names, see ``A closer look at TrueType fonts and +\PDFTEX'', {\em TUGboat} 30:1 (2009), pp.~32||34, \from[thanh_truetype_tub] + +%*********************************************************************** + +\section{Formal syntax specification} + +This section formally specifies the \PDFTEX-specific extensions to the +\TEX\ macro programming language. Most primitives are prefixed by +\type{pdf}. The general definitions and syntax rules follow after the +list of primitives. + +Two new units of measure were introduced in \PDFTEX\ 1.30.0: the +new Didot (1\,nd~=~0.375\,mm) and the new Cicero (1\,nc~=~12\,nd) +(the former was proposed by \ISO\ in 1975). + +% Generated list of primitives (see Makefile). +\input pdftex-syntax.tex + +\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{dimen} \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{colorspace spec} \Means % + \Literal{colorspace} \Something{number} +} + +\Syntax{ +\Something{pdf box spec} \Means % + \Literal{mediabox} % + \Or \Literal{cropbox} % + \Or \Literal{bleedbox} % + \Or \Literal{trimbox} % + \Or \Literal{artbox} +} + +\Syntax{ +\Something{map spec} \Means % + \Lbrace \Optional{\Something{map modifier}} % + \Something{balanced text} \Rbrace +} + +\Syntax{ +\Something{map modifier} \Means % + \Literal{+} \Or \Literal{=} \Or \Literal{-} +} + +\Syntax{ +\Something{numid} \Means % + \Literal{num} \Something{number} +} + +\Syntax{ +\Something{nameid} \Means % + \Literal{name} \Something{general text} +} + +\Syntax{ +\Something{newwindow spec} \Means % + \Literal{newwindow} \Or \Literal{nonewwindow} +} + +\Syntax{ +\Something{dest spec} \Means % + \Something{numid} \Something{dest type} + \Or \Something{nameid} \Something{dest type} +} + +\Syntax{ +\Something{dest type} \Means % + \Literal{xyz} \Optional{\Literal{zoom} \Something{number}} + \Or \Literal{fitr} \Something{rule spec} + \Or \Next \Literal{fitbh} + \Or \Literal{fitbv} + \Or \Literal{fitb} + \Or \Literal{fith} + \Or \Literal{fitv} + \Or \Literal{fit} +} + +\Syntax{ +\Something{thread spec} \Means % + \Optional{\Something{rule spec}} % + \Optional{\Something{attr spec}} % + \Something{id spec} +} + +\Syntax{ +\Something{id spec} \Means % + \Something{numid} \Or \Something{nameid} +} + +\Syntax{ +\Something{file spec} \Means % + \Literal{file} \Something{general text} +} + +\Syntax{ +\Something{page spec} \Means % + \Literal{page} \Something{number} +} + +\Syntax{ +\Something{expand spec} \Means % + \Something{stretch} % + \Something{shrink} % + \Something{step} % + \Optional{\Literal{autoexpand}} +} + +\Syntax{ +\Something{stretch} \Means % + \Something{number} +} + +\Syntax{ +\Something{shrink} \Means % + \Something{number} +} + +\Syntax{ +\Something{step} \Means % + \Something{number} +} + +\Syntax{ +\Something{pre spec} \Means % + \Literal{pre} +} + +\Syntax{ +\Something{pdfliteral spec} \Means % + \Literal{direct} \Or \Literal{page} +} + +\Syntax{ +\Something{pdfspecial spec} \Means % + \Lbrace \Optional{\Something{pdfspecial id} % + \Optional{\Something{pdfspecial modifier}}} % + \Something{balanced text} \Rbrace +} + +\Syntax{ +\Something{pdfspecial id} \Means % + \Literal{pdf:} \Or \Literal{PDF:} +} + +\Syntax{ +\Something{pdfspecial modifier} \Means % + \Literal{direct:} +} + +\Syntax{ +\Something{stack action} \Means % + \Literal{set} \Or \Literal{push} \Or \Literal{pop} \Or \Literal{current} +} + +\stoppacked + +A \Something{general text} is expanded immediately, like \type{\special} +in traditional \TEX, unless explicitly mentioned otherwise. + +Some of the object and image related primitives can be prefixed by +\type{\immediate}. More about that in the next sections. + +%*********************************************************************** + +\section[primitives]{\PDFTEX\ primitives} + +Here follows a description of the primitives added by \PDFTEX\ to the +original \TEX\ engine (other extensions by \ETEX, \MLTEX\ and \ENCTEX\ +are not listed). Many of these primitives are described further in the +\filename {samplepdf.tex} file in the \PDFTEX\ distribution. + +If the output is \DVI, then the \PDFTEX-specific dimension parameters +are not used at all. However, some \PDFTEX\ integer parameters can +affect \DVI\ as well as \PDF\ output (specifically, \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{\tex{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{\tex{pdfminorversion}} + +This primitive sets the \PDF\ version of the generated file and the +highest \PDF\ version of included \PDF{}s allowed without warning, by +default (see \type{\pdfinclusionerrorlevel}). The default compiled into +the \PDFTEX\ program is \type{\pdfminorversion=4}, setting the \PDF\ +version to~1.4 and allowing included \PDF\ files with versions up +to~1.4. If specified, this primitive must appear before any data is to +be written to the generated \PDF\ file. + +Distributions typically alter the engine's compiled default of~4 when +building formats; for example, as of 2010, \TEXLIVE\ sets +\type{\pdfminorversion=5} when formats are built. This is so object +compression can be enabled (described below). + +This was originally a shortened synonym of the +\type{\pdfoptionpdfminorversion} command, which is now obsolete. +\introduced{1.30.0} + + +\pdftexprimitive{\Syntax{\Tex{\pdfcompresslevel} \Whatever{integer}}} +\bookmark{\tex{pdfcompresslevel}} + +This integer parameter specifies the level of {\em stream} compression +(text, inline 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 useful for \PDF\ stream debugging. + +\pdftexprimitive{\Syntax{\Tex{\pdfobjcompresslevel} \Whatever{integer}}} +\bookmark{\tex{pdfobjcompresslevel}} + +This integer parameter controls the compression of {\em non-stream} +objects. In the \PDF-1.4 specification these objects still had to go into +the \PDF\ file as clear text, uncompressed. The \PDF-1.5 specification +now allows to collect non-stream objects as ``compressed objects'' into +``object stream'' objects (\type{/Type /ObjStm}, see \PDF\ Ref.\ 5th~ed., +sect.~3.4.6). At the \PDF\ file end instead of the object table then +an \type{/XRef} cross-reference stream is written out. This results in +considerably smaller \PDF\ files, particularly if lots of annotations +and links are used. +\introduced{1.40.0} + +The writing of compressed objects is enabled by setting +\type{\pdfobjcompresslevel} to a value between~1 and~3; it's +disabled by value~0 (default). Enabling requires that also +\type{\pdfminorversion}~$>$~4. If \type{\pdfobjcompresslevel}~$>$~0, +but \type{\pdfminorversion}~$<$~5, a warning is given and object stream +writing is disabled. The \type{\pdfobjcompresslevel} value is clipped +to the range $0..3$. Using values outside this range is not recommended +(for future extension). + +The \type{\pdfobjcompresslevel} settings have the following effects: +When set to~0, no object streams are generated at all. When set to~1, +all non-stream objects are compressed with the exception of any objects +coming with embedded \PDF\ files (``paranoid'' mode, to avoid yet unknown +problems), and also the \type{/Info} dictionary is not compressed for +clear-text legibility. When set to~2, also all non-stream objects coming +with embedded \PDF\ files are compressed, but the \type{/Info} dictionary +is still not compressed. Finally, when set to~3, all non-stream objects +are compressed, including the \type{/Info} dictionary (this means that +the \type{/Info} can't be read as clear text any more). If object streams +are to be used, currently \type{\pdfobjcompresslevel=2} is recommended, +and is so specified in some distributions, including \TEXLIVE~2010 and later. + +\description{Caveat:} \PDF\ files generated with object streams enabled +can't be read with (sufficiently old) \PDF\ viewers that don't +understand \PDF-1.5 files. For widest distribution and unknown audience, +don't activate object stream writing. The \PDF-1.5 standard describes +also a hybrid object compression mode that gives some backward +compatibility, but this is currently not implemented, as \PDF-1.5 was +rather quickly adopted by modern \PDF\ viewers. Also not implemented is +the optional \type{/Extends} key. + +\pdftexprimitive{\Syntax{\Tex{\pdfdecimaldigits} \Whatever{integer}}} +\bookmark{\tex{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{dimen}}} +\bookmark{\tex{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{dimen}}} +\bookmark{\tex{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{dimen}}} +\bookmark{\tex{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{dimen}}} +\bookmark{\tex{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[sec.docinfocatalog]{The document info and catalog} + +\pdftexprimitive{\Syntax{\Tex{\pdfinfo} \Something{general text}}} +\bookmark{\tex{pdfinfo}} + +This primitive allows the user to specify information for the document +info dictionary; if this information is provided, it can be extracted, +\eg\ by the \type{pdfinfo} program. 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, and the primitive itself, are optional. Possible +keys are:\crlf +\type{/Title},\crlf +\type{/Author},\crlf +\type{/Subject},\crlf +\type{/Keywords},\crlf +\type{/Producer} (defaults to \hbox{\tt pdfTeX-\currentpdftex}),\crlf +\type{/Creator} (defaults to \type{TeX}),\crlf +\type{/CreationDate} (defaults to current date and time, with time zone),\crlf +\type{/ModDate} (same default),\crlf +\type{/Trapped} (defaults to \type{/False},\crlf +\type{/PTEX.Fullbanner} (defaults to the \type{\pdftexbanner} string, q.v.). + +\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, \type{Z} for universal time. For example, this +is the Unix epoch, the beginning of 1970-01-01 UTC, in this format: +\type{19700101000000Z}. If the time zone is not UTC, it is given as +\type{+HH'mm'} or \type{-HH'mm'}, indicating an offset of the given +hours and minutes from UTC, with the given either later (\type{+}) or +earlier (\type{-}) than UTC. (This syntax is specified by the PDF +definition.) + +Multiple appearances of \type{\pdfinfo} are concatenated. Usually if a +key is given more than once, the first appearance will be used, but this +is viewer||dependent. Except for standard \TeX\ expansion, \PDFTEX\ does +not perform any further operations in the \Something{general text} +provided by the user. + +Here is an example of using \type{\pdfinfo} to include the +information not supplied by \PDFTEX: + +\starttyping +\pdfinfo { + /Title (example.pdf) + /Author (Tom and Jerry) + /Subject (Example) + /Keywords (mouse, cat) +} +\stoptyping + +For more details on all this, see the \PDFReference. + +\pdftexprimitive{\Syntax{\Tex{\pdfinfoomitdate} \Whatever{integer}}} +\bookmark{\tex{pdfinfoomitdate}} + +If nonzero, omit the \type{/CreationDate} and \type{/ModDate} keys from +the document info dictionary described above. This can be useful in +making reproducible \PDF{}s. \introduced{1.40.17} + +\pdftexprimitive{\Syntax{\Tex{\pdfsuppressptexinfo} \Whatever{integer}}} +\bookmark{\tex{pdfsuppressptexinfo}} + +Treated as a bitmask, specifying which \type{PTEX.*} keys to omit from +the output: + +\startbuffer +\starttabulate[|l|l|] +\HL +\NC \bf value \NC \bf suppresses \NC\NR +\HL +\NC \tt 1 \NC \type{PTEX.Fullbanner} \NC\NR +\NC \tt 2 \NC \type{PTEX.FileName} \NC\NR +\NC \tt 4 \NC \type{PTEX.PageNumber} \NC\NR +\NC \tt 8 \NC \type{PTEX.InfoDict} \NC\NR +\HL +\stoptabulate +\stopbuffer + +\placetable + [here][suppressptexinfo] + {\type{\pdfsuppressptexinfo} bit meanings.} + {\getbuffer} + +Thus, the value \type{-1}, or the sum of all defined bits, will suppress +everything. + +\type{PTEX.Fullbanner} is included by default in the general document +info dictionary, as mentioned under \type{\pdfinfo} above. The other +\type{PTEX.*} keys are included when a \PDF\ is included in the document +(and not otherwise), as described in \in{section}[sec.addpdfkeys]. + +This conditional suppression can be useful in making reproducible +\PDF{}s. \introduced{1.40.17} + +\pdftexprimitive{\Syntax{\Tex{\pdfcatalog} \Something{general text} + \Optional{\Literal{openaction} \Something{action spec}}}} +\bookmark{\tex{pdfcatalog}} + +Similar to the document info section is the document catalog, where +possible keys are \type{/URI}, which specifies 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} + +The default \type{/PageMode} setting is \type{/UseNone}. In +full||screen mode, there is no menu bar, window controls, nor any other +window present. + +After the \Something{general text}, a construct \Literal{openaction} +\Something{action spec} can be given, where \Literal{openaction} is a +\PDFTEX\ keyword, and \Something{action spec} specifies the action to be +taken when opening the document. This \Something{action spec} is the +same as for internal links; see \in {section} [linking]. (Instead of +using this method, one can also write the open action directly into the +catalog.) + +Several settings can be made in one \type{\pdfcatalog} call, for +example: + +\starttyping +\pdfcatalog{ + /PageMode /FullScreen +} openaction goto page 2 {/Fit} +\stoptyping + +\pdftexprimitive{\Syntax{\Tex{\pdfnames} \Something{general text}}} +\bookmark{\tex{pdfnames}} + +This primitive inserts the \Something{general text} to the \type +{/Names} array. The text must +conform to the specifications as laid down in the \PDFReference, +otherwise the document can be invalid. + +\pdftexprimitive{\Syntax{\Tex{\pdftrailer} \Something{general text}}} +\bookmark{\tex{pdftrailer}} + +This command puts its argument text verbatim into the file trailer +dictionary. Example: \type{\pdftrailer {/mytrlrkey /mytrlrval}}. +\introduced{1.11a} + +\pdftexprimitive{\Syntax{\Tex{\pdftrailerid} \Something{general text}}} +\bookmark{\tex{pdftrailerid}} + +Use the \Something{general text} to seed the \type{/ID} value in the +trailer, instead of the default combination of the input file +name and starting time. If the argument is empty, the \type{/ID} is +omitted entirely. Example: \type{\pdftrailerid{}}. This can be useful +in making reproducible \PDF{}s. \introduced{1.40.17} + +%*********************************************************************** + +\subsection{Fonts} + +\pdftexprimitive{\Syntax{\Tex{\pdfpkresolution} \Whatever{integer}}} +\bookmark{\tex{pdfpkresolution}} + +This integer parameter specifies the default resolution of embedded \PK\ +fonts and is read when \PDFTEX\ embeds a \PK\ font during finishing the +\PDF\ output. As bitmap fonts are still rendered poorly by some \PDF\ +viewers, it is best to use Type~1 fonts when available. + +\pdftexprimitive{\Syntax{\Tex{\pdffontexpand} + \Something{font} \Something{stretch} \Something{shrink} + \Something{step} \Optional{\Literal{autoexpand}}}} +\bookmark{\tex{pdffontexpand}} + +This extension to \TEX's font definitions controls a major \PDFTEX\ feature +called {\em font expansion}. We describe this by an example: + +\starttyping +\font\somefont=sometfm at 10pt +\pdffontexpand\somefont 30 20 10 autoexpand +\pdfadjustspacing=2 +\stoptyping + +The \type{30 20 10} means this: \quotation {hey \TEX, when line breaking +is going badly, you may stretch the glyphs from this font as much as +3\,\% or shrink them as much as 2\,\%}. For practical reasons \PDFTEX\ +uses discrete expansion steps, in this example, 1\,\%. Roughly spoken, the +trick is as follows. Consider a text typeset in triple column mode. When +\TEX\ cannot break a line in the appropriate way, the unbreakable parts +of the word will stick into the margin. When \PDFTEX\ notes this, it +will try to scale (shrink) the glyphs in that line using fixed steps, +until the line fits. When lines are too spacy, the opposite happens: +\PDFTEX\ starts scaling (stretching) the glyphs until the white space +gaps is acceptable. This glyph stretching and shrinking is called +{\em font expansion}. To enable font expansion, don't forget to set +\type{\pdfadjustspacing} to a value greater than zero. + +There are two different modes for font expansion: + +First, if the \type{autoexpand} option is given --- which is the +recommended mode --- only a single map entry is needed for all expanded +font versions, using the name of the unexpanded \TFM\ file ({\em +tfmname}). No expanded {\em tfmname} versions need to mentioned (they are +ignored), as \PDFTEX\ generates expanded copies of the unexpanded \TFM\ +data structures and keeps them in its memory. Since \PDFTEX~1.40.0 the +\type{autoexpand} mode happens within the page stream by modification of +the text matrix (\PDF\ operator ``\type{Tm}''), and not anymore on font +file level, giving the advantage that it now works not only with Type~1 +but also with TrueType and OpenType fonts (and even without embedding +a font file; but that's not recommended). In this mode \PDFTEX\ requires +only unexpanded font files. + +Second, if the \type{autoexpand} option is missing, setting up font +expansion gets more tedious, as there must be map entries for \TFM\ files +in all required expansion values. The expanded {\em tfmname} variants +are constructed by adding the font expansion value to the {\em tfmname} +of the base font, \eg\ there must be a map entry with {\em tfmname} +\type{sometfm+10} for 1\,\% stretch or \type{sometfm-15} for 1.5\,\% +shrink. This also means, that for each expanded font variant a \TFM\ +file with properly expanded metrics must exist. Having several map +entries for the various expansion values of a font requires to provide +for each expansion value an individually crafted font file with expanded +glyphs. Depending on how these glyphs are generated, this might give +slightly better glyph forms than the rather simple glyph stretching +used in \type{autoexpand mode}. The drawback is that several font +files will be embedded in the \PDF\ output for each expanded font, +leading to significantly larger \PDF\ files than in \type{autoexpand} +mode. For moderate expansion values going without \type{autoexpand} +mode is not worth the trouble. + +The font expansion mechanism is inspired by an optimization first +introduced by Prof.~Hermann Zapf, which in itself goes back to +optimizations used in the early days of typesetting: use different +glyphs to optimize the grayness of a page. So, there are many, slightly +different~a's, e's, etc. For practical reasons \PDFTEX\ does not use +such huge glyph collections; it uses horizontal scaling instead. This is +sub||optimal, and for many fonts, possibly offensive to the design. But, +when using \PDF, it's not illogical: \PDF\ viewers use so||called +Multiple Master fonts when no fonts are embedded and|/|or can be found +on the target system. Such fonts are designed to adapt their design to +the different scaling parameters. It is up to the user to determine +to what extent mixing slightly remastered fonts can be used without +violating the design. Think of an O: when geometrically stretched, the +vertical part of the glyph becomes thicker, and looks incompatible with +an unscaled original. With a Multiple Master situation, one can stretch +while keeping this thickness compatible. + +\pdftexprimitive{\Syntax{\Tex{\pdfadjustspacing} \Whatever{integer}}} +\bookmark{\tex{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\ +behavior. + +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} + \Something{8-bit number} \Whatever{integer}}} +\bookmark{\tex{efcode}} + +We haven't yet told 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. + +Changes to this table are global, i.e., ignore \TeX's usual grouping, +and apply only to the given \Something{font}. + +\pdftexprimitive{\Syntax{\Tex{\pdfprotrudechars} \Whatever{integer}}} +\bookmark{\tex{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} + \Something{8-bit number} \Whatever{integer}}} +\bookmark{\tex{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. + +Changes to this table are global, i.e., ignore \TeX's usual grouping, +and apply only to the given \Something{font}. + +\pdftexprimitive{\Syntax{\Tex{\lpcode} \Something{font} + \Something{8-bit number} \Whatever{integer}}} +\bookmark{\tex{lpcode}} + +This is similar to \type{\rpcode}, but affects the amount by which +characters may protrude into the left margin. Here also the given integer +value is clipped to the range $-1000..1000$. + +Changes to this table are global, i.e., ignore \TeX's usual grouping, +and apply only to the given \Something{font}. + +\pdftexprimitive{\Syntax{\Tex{\leftmarginkern} \Something{box number} + \Whatever{expandable}}} +\bookmark{\tex{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 +unpacking 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{\tex{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{\letterspacefont} \Something{control sequence} + \Something{font} \Something{integer}}} +\bookmark{\tex{letterspacefont}} + +This primitive creates an instance of \Something{font} with the widths +of all glyphs increased by \Something{integer} thousandths of an em (as +set in \Something{font}). The effect is letter spacing, but the glyphs +are actually larger (sidebearings are increased), so a single glyph will +take more space. For instance, the following creates a font +\type{\lsfont} whose glyphs are all 1.2\,pt larger than those of +\type{\normalfont}: + +\starttyping +\font\normalfont=myfont at 12pt +\letterspacefont\lsfont\normalfont 100 +\stoptyping + +Negative values are allowed for \Something{integer}. +Letter spacing works natively in \PDF\ mode only, unless special fonts are +devised (in our example, a \type{myfont+100ls} font), as with font expansion. + +\pdftexprimitive{\Syntax{\Tex{\pdfcopyfont} \Something{control sequence} + \Something{font}}} +\bookmark{\tex{pdfcopyfont}} + +This primitive defines \Something{control sequence} as a synonym for +\Something{font}. + +\pdftexprimitive{\Syntax{\Tex{\pdffontattr} \Something{font} + \Something{general text}}} +\bookmark{\tex{pdffontattr}} + +This primitive inserts the \Something{general text} to the \type{/Font} +dictionary. The text must conform to the specifications as laid down in +the \PDFReference, otherwise the document can be invalid. For examples, +see the \type{cmap} and \type{CJK} packages. + +\pdftexprimitive{\Syntax{\Tex{\pdffontname} \Something{font} + \Whatever{expandable}}} +\bookmark{\tex{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{\tex{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{\tex{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} \Whatever{expandable}}} +\bookmark{\tex{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{\tex{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{\tex{pdfmapfile}} + +This primitive is used for reading a font map file consisting of +one or more font map lines. The name of the map file is given in +the \Something{map spec} together with an optional leading modifier +character. If no \type{\pdfmapfile} primitive is given, the default map +file \filename{pdftex.map} will be read by \PDFTEX. There is a companion +primitive \type{\pdfmapline} that allows to scan single map lines; +its map line argument has the same syntax as the map lines from a map +file. Both primitives can be used concurrently. The \type{\pdfmapfile} +primitive is fast for reading external bulk font map information (many +map lines collected in a map file), whereas the \type{\pdfmapline} allows +to put the font map information for individual \TeX\ fonts right into +the \TeX\ source or a style file. In any case the map line information +is scanned by \PDFTEX, and in the most common case the data are put into +a fresh internal map entry data structure, which is then consulted once +a font is called. + +Normally there is no need for the \PDFTEX\ user to bother about the +\type{\pdfmapfile} or \type{\pdfmapline} primitives, as the main \TEX\ +distributions provide nice helper tools that automatically assemble +the default font map file. Prominent tool examples are the scripts +\type{updmap} and \type{updmap-sys} coming with \TEXLIVE\ and \TETEX. +If your map file isn't in the current directory (or a standard system +directory), you will need to set the \type{TEXFONTMAPS} variable (in +\WEBC) or give an explicit path so that it will be found. + +When the \type{\pdfmapfile} or \type{\pdfmapline} primitive is read +by \PDFTEX, the argument (map file or map line) will be processed +{\em immediately}, and the internal map entry database is updated. +The operation mode of the \type{\pdfmapfile} and \type{\pdfmapline} +primitives is selected by an optional modifier character (\type{+}, +\type{=}, \type{-}) in front of the {\em tfmname} field. This modifier +defines how the individual map lines are going to be handled, and how +a collision between an already registered map entry and a newer one is +resolved; either ignoring a later entry, or replacing or deleting an +existing entry. But in any case, map entries of fonts already in use +are kept untouched. Here are two examples: + +\starttyping +\pdfmapfile{+myfont.map} +\pdfmapline{+ptmri8r Times-Italic <8r.enc <ptmri8a.pfb} +\stoptyping + +When no modifier character is given (\eg\ \type{\pdfmapfile{foo.map}} +or \type{\pdfmapline{phvr8r Helvetica}}) and there hasn't already been +any call of one of these primitives before, then the default map file +\filename{pdftex.map} will {\em not} be read in. Apart from this the +given map file will be processed similarly as with a \type{+} modifier: +duplicate later map entries within the file are ignored and a warning is +issued. This means, that you can block reading of the default map file +also by an empty \type{\pdfmapfile{}} or \type{\pdfmapline{}} early in +the \TeX\ file. When the default map file is large but you don't need it +anyway, these command variants might considerably speed up the \PDFTEX\ +startup process. + +If a modifier is given, the mechanism is so that before reading the +items given as arguments to \type{\pdfmapfile} or \type{\pdfmapline} +the default map file will be read first --- if this hasn't already +been done or been prevented by the above blocking cases. This should +be mostly compatible with the traditional behavior. If you want to add +support for a new font through an additional font map file while keeping +all the existing mappings, don't use the primitive versions without +modifier, but instead type either \type{\pdfmapfile{+myfont.map}} or +\type{\pdfmapfile{=myfont.map}}, as described below. + +\type{\pdfmapfile {+foo.map}} reads the file \filename{foo.map}; duplicate +later map entries within the file are ignored and a warning is issued. + +\type{\pdfmapfile {=foo.map}} reads the file \filename{foo.map}; +matching map entries in the database are replaced by new entries from +\filename{foo.map} (if they aren't already in use). + +\type{\pdfmapfile {-foo.map}} reads the file \filename{foo.map}; matching +map entries are deleted from the database (if not yet in use). + +If you want to use a base map file name other than \type{pdftex.map}, +or change its processing options through a \PDFTEX\ format, you can do +this by appending the \type{\pdfmapfile} command to the \type{\everyjob{}} +token list for the \type{-ini} run, \eg: + +\starttyping +\everyjob\expandafter{\the\everyjob\pdfmapfile{+myspecial.map}} +\dump +\stoptyping + +This would always read the file \type{myspecial.map} after the default +\type{pdftex.map} file. + + +\pdftexprimitive{\Syntax{\Tex{\pdfmapline} \Something{map spec}}} +\bookmark{\tex{pdfmapline}} + +Similar to \type{\pdfmapfile}, but here you can give a single +map line (like the ones in map files) as an argument. The optional modifiers +(\type{+-=}) have the same effect as with \type{\pdfmapfile}; see also +the description above. Example: + +\starttyping +\pdfmapline{+ptmri8r Times-Italic <8r.enc <ptmri8a.pfb} +\stoptyping + +This primitive (especially the \type{\pdfmapline{=...}} variant) is useful +for temporary quick checks of a new font map entry during development, +before finally putting it into a map file. + +\type{\pdfmapline {}} like \type{\pdfmapfile {}} blocks reading +of the default map file, if it comes early enough in the \TeX\ +input. \introduced{1.20a} + + +\pdftexprimitive{\Syntax{\Tex{\pdfsuppresswarningdupmap} \Whatever{integer}}} +\bookmark{\tex{pdfsuppresswarningdupmap}} + +Ordinarily, \PDFTEX\ gives a warning when a duplicate map entry for a +given font is read, whatever the mechanism. However, sometimes it is +useful to include map information within the document, using +\type{\pdfmapfile} or \type{\pdfmapline}, even for fonts that happen to +be installed on the system. Then seeing the warnings on every run is +just noise, and can be suppressed by setting this parameter to a +positive number. \introduced{1.40.13} + +\pdftexprimitive{\Syntax{\Tex{\pdftracingfonts} \Whatever{integer}}} +\bookmark{\tex{pdftracingfonts}} + +This integer parameter specifies the level of verbosity for info about +expanded fonts given in the log, \eg\ when \type{\tracingoutput=1}. +If \type{\pdftracingfonts=0}, which is the default, the log shows the +actual non-zero signed expansion value for each expanded letter within +brackets, \eg: + +\starttyping +...\xivtt (+20) t +\stoptyping + +If \type{\pdftracingfonts=1}, also the name of the \TFM\ file is listed, +together with the font size, \eg: + +\starttyping +...\xivtt (cmtt10+20@14.0pt) t +\stoptyping + +Setting \type{\pdftracingfonts} to a value other than~0 or~1 is not +recommended, to allow future extensions. \introduced{1.30.0} + +\pdftexprimitive{\Syntax{\Tex{\pdfmovechars} \Whatever{integer}}} +\bookmark{\tex{pdfmovechars}} + +Since \PDFTEX\ version 1.30.0 the primitive \type{\pdfmovechars} is obsolete, +and its use merely leads to a warning. (This primitive specified whether +\PDFTEX\ should try to move characters in range 0..31 to higher slots; +its sole purpose was to remedy certain bugs of early \PDF\ viewers.) + +\pdftexprimitive{\Syntax{\Tex{\pdfpkmode} \Whatever{tokens}}} +\bookmark{\tex{pdfpkmode}} + +The \type{\pdfpkmode} is a token register that sets the \METAFONT\ mode for +pixel font generation. The contents of this register is dumped into the +format, so one can (optionally) preset it \eg\ in \type{pdftexconfig.tex}. +\introduced{1.30.0} + +\pdftexprimitive{\Syntax{\Tex{\pdfnoligatures} \Something{font}}} +\bookmark{\tex{pdfnoligatures}} + +This disables all ligatures in the loaded font \Something{font}. +\introduced{1.30.0} + +\pdftexprimitive{\Syntax{\Tex{\tagcode} \Something{font} + \Something{8-bit number} \Whatever{integer}}} +\bookmark{\tex{tagcode}} + +This primitive accesses a character's \type{char_tag} info. It is meant +to delete \type{lig_tag} (the character's ligature/kerning program), +\type{list_tag} (which indicates that the character belongs to a chain of +ascending sizes) and/or \type{ext_tag} (which indicates that the character +is extensible), with the following options: assigning \type{-7} or smaller +clears all tags, \type{-6} clears \type{ext_tag} and \type{list_tag}, +\type{-5} clears \type{ext_tag} and \type{lig_tag}, \type{-4} clears +\type{ext_tag}, \type{-3} clears \type{list_tag} and \type{lig_tag}, +\type{-2} clears \type{list_tag}, \type{-1} clears \type{lig_tag}, +and \type{0} or larger does nothing. Changes are irreversible and global. + +Conversely, when queried, the primitive returns \type{0} if the tag's +value is \type{no_tag}, \type{1} if \type{lig_tag} is set, \type{2} if +\type{list_tag} is set or \type{4} (not~3) if \type{ext_tag} is set. + +\pdftexprimitive{\Syntax{\Tex{\pdfgentounicode} \Whatever{integer}}} + +By default, \PDFTEX\ does not include a \type{/ToUnicode} resource when +including fonts in the output. Such a resource (also called a CMap +resource) maps glyph names to Unicode characters in a \PDF\ file. +Lacking such a resource, it is the \PDF\ reader which determines how and +whether searching in the \PDF\ file works. In practice, searching for +basic ASCII characters generally works, but searching for anything +beyond those, including ligatures such as `fi', fails in some versions +of some PDF browsers (most notably Adobe Reader). + +If \type{\pdfgentounicode} is set to \type{1} when the job ends, the +\type{/ToUnicode} resource will be included in the output, with mappings +for Type~1 fonts used in the documents. The mapping is created as +follows: for each glyph in the font, look for its \type{ToUnicode} value +in a global hash table. By default that global hash table is empty; +entries are added to the table using the following command: + +\pdftexprimitive{\Syntax{\Tex{\pdfglyphtounicode} \Something{general text} + \Something{general text}}} + +The first argument is the name of a glyph, the second is a string of Unicode +numeric values denoting characters, separated by spaces. For instance: + +\starttyping +\pdfgentounicode=1 +\pdfglyphtounicode{ff}{0066 0066} +\stoptyping + +\noindent maps the \type{ff} ligature to a pair of \type{f}'s (whose +code is \type{U+0066}). + +The \type{glyphtounicode.tex} file (distributed with \PDFTEX\ and other +software) contains thousands of such definitions, covering most common +glyph names. So, for practical purposes, one would probably want: + +\starttyping +\input glyphtounicode +\pdfgentounicode=1 +\stoptyping + +\LATEX\ users could load the \type{cmap} package to achieve the same +effect. + + +\pdftexprimitive{\Syntax{\Tex{\pdfnobuiltintounicode} \Something{font}}} + +The primary purpose of this command is to prevent \PDFTEX\ from +generating the \type{ToUnicode}/CMap resource for the given font when +\type{\pdfgentounicode=1}, most likely because the CMap resource is +already generated by some other method (for example, the \LATEX\ +\type{cmap} package uses \type{\pdffontattr} to generate a CMap +resource). + +Minimal example: +\starttyping +\font\f=cmb10 +\pdfnobuiltintounicode\f +\f No unicode mappings for this output. +\stoptyping +\introduced{1.40.11} + + +\pdftexprimitive{\Syntax{\Tex{\pdfinterwordspaceon}}} +\pdftexprimitive{\Syntax{\Tex{\pdfinterwordspaceoff}}} + +These commands create corresponding whatsit nodes which turn on/off +generation of faked interword spaces in the output. This allows for +better reflowing of text on the fly by \PDF\ readers, better extraction +of textual content, and is required by \PDF/A. It does not affect the +normal \TeX\ justification with glue. + +This requires finding and reading font files \type{dummy-space.tfm} and +\type{pfb}; the font is included in the \PDF\ output and character 32 is +inserted from it as the ``fake'' space. + +Example of usage (see also the \type{fake-interword-space.tex} test file): + +\starttyping +Text with no interword spaces. + +\pdfmapline{+dummy-space <dummy-space.pfb} +\pdfglyphtounicode{space}{0020} +\pdfinterwordspaceon + +Switch to text with faked interword spaces. + +\pdfinterwordspaceoff + +Back to text with no interword spaces. +\stoptyping +\introduced{1.40.15} + +\pdftexprimitive{\Syntax{\Tex{\pdffakespace}}} + +Insert a faked interword space to the output, regardless of the value of +\type{\pdfinterwordspaceon} and \type{\pdfinterwordspaceoff}. Example: + +\starttyping +Text with no interword \pdffakespace\pdffakespace spaces. +\stoptyping +\introduced{1.40.15} + +%*********************************************************************** + +\subsection{Spacing} + +Controlling spacing before and after characters was introduced in +version 1.30, mostly to handle punctuation rules in different +languages. The \type{\...code} tables here, like those in the previous +section, operate globally, i.e., ignore \TeX's usual grouping, and apply +only to the given \Something{font}, not other instances of the +underlying font. + +\pdftexprimitive{\Syntax{\Tex{\pdfadjustinterwordglue} \Whatever{integer}}} +\bookmark{\tex{pdfadjustinterwordglue}} + +If positive, adjustment of interword glue is enabled and controlled by the +following three primitives. + +\pdftexprimitive{\Syntax{\Tex{\knbscode} \Something{font} + \Something{8-bit number} \Whatever{integer}}} +\bookmark{\tex{knbscode}} + +The amount of space, in thousandths of an em, added to the natural width +of the glue following a character (the name stands for ``kern before +space'', although technically it is looking at glue items, not kern +items). This amounts is clipped to the range $-1000..1000$. For +instance, the following example means that glues after periods will be +increased by .2\,em. + +\starttyping +\pdfadjustinterwordglue=1 +\knsbcode\font`\.=200 +\stoptyping + +\pdftexprimitive{\Syntax{\Tex{\stbscode} \Something{font} + \Something{8-bit number} \Whatever{integer}}} +\bookmark{\tex{stbscode}} + +This works like \type{\knbscode}, but applies to the stretch component of +the following glue. + +\pdftexprimitive{\Syntax{\Tex{\shbscode} \Something{font} + \Something{8-bit number} \Whatever{integer}}} +\bookmark{\tex{shbscode}} + +Like \type{\stbscode}, but for the shrink component. + +\pdftexprimitive{\Syntax{\Tex{\pdfprependkern} \Whatever{integer}}} +\bookmark{\tex{pdfprependkern}} + +If positive, automatic insertion of kerns before characters is enabled. + +\pdftexprimitive{\Syntax{\Tex{\knbccode} \Something{font} + \Something{8-bit number} \Whatever{integer}}} +\bookmark{\tex{knbccode}} + +The width of the kern, in thousandths of an em, inserted before a character. +It is clipped to the range $-1000..1000$. For instance, with the +following code, a .15\,em-kern will be inserted before all question marks +(useful for \eg\ French punctuation): + +\starttyping +\pdfprependkern=1 +\knbccode\font`\?=150 +\stoptyping + +\pdftexprimitive{\Syntax{\Tex{\pdfappendkern} \Whatever{integer}}} +\bookmark{\tex{pdfappendkern}} + +Same as \type{\pdfprependkern}, but for kerns inserted after characters. + +\pdftexprimitive{\Syntax{\Tex{\knaccode} \Something{font} + \Something{8-bit number} \Whatever{integer}}} +\bookmark{\tex{knaccode}} + +Same as \type{\knbccode}, except the kern is inserted after the +character. Such a kern is required for instance after a left guillemet +in French punctuation. + +%*********************************************************************** + +\subsection{Vertical adjustments} + +\pdftexprimitive{\Syntax{\Tex{\pdfignoreddimen} \Whatever{dimen}}} +\bookmark{\tex{pdfignoreddimen}} + +This is the dimension which must assigned to the following four primitives +so they are ignored. Default is \type{-1000pt}, and it should be modified +with care since it also influences when a previous paragraph's depth is ignored +(for instance, the plain \TEX\ macro \type{\nointerlineskip} should be +modified accordingly). + +\pdftexprimitive{\Syntax{\Tex{\pdffirstlineheight} \Whatever{dimen}}} +\bookmark{\tex{pdffirstlineheight}} + +This parameter specifies the height of the first line of a paragraph, +regardless of its content. It is read when the paragraph builder is +called, and ignored when set to \type{\pdfignoreddimen}. By default, +it is set to \type{-1000pt}, so it is ignored as long as the value +of \type{\pdfignoreddimen} is the same. + +\pdftexprimitive{\Syntax{\Tex{\pdflastlinedepth} \Whatever{dimen}}} +\bookmark{\tex{pdflastlinedepth}} + +This is similar to the previous parameter, but affects the last line's +depth of a paragraph. + +\pdftexprimitive{\Syntax{\Tex{\pdfeachlineheight} \Whatever{dimen}}} +\bookmark{\tex{pdfeachlineheight}} + +Similar to \type{\pdffirstlineheight}, but for all lines of a paragraph, +including the first one, unless \type{\pdffirstlineheight} is specified. + +\pdftexprimitive{\Syntax{\Tex{\pdfeachlinedepth} \Whatever{dimen}}} +\bookmark{\tex{pdfeachlinedepth}} + +Like the preceding parameter, but for depth. + +%*********************************************************************** + +\subsection{\PDF\ objects} + +\pdftexprimitive{\Syntax{\Tex{\pdfobj} \Something{object type spec} + \Modelist{h, v, m}}} +\bookmark{\tex{pdfobj}} + +This command creates a raw \PDF\ object that is written to the \PDF\ +file as \type{1 0 obj} \unknown\ \type{endobj}. The object is written to +\PDF\ output as provided by the user. When \Something{object type spec} +is not given, \PDFTEX\ no longer creates a dictionary object with +contents \Something{general text}, as it did in the past. + +When, however, \Something{object type spec} is given as \Something{attr +spec} \Literal{stream}, the object will be created as a stream with +contents \Something{general text} and additional attributes in +\Something{attr spec}\unkern. + +When \Something{object type spec} is given as \Something{attr spec} +\Literal{file}, then the \Something{general text} will be treated as a file +name and its contents will be copied into the stream contents. + +When \Something{object type spec} is given as \type{reserveobjnum}, +just a new object number is reserved. The number of the reserved object +is accessible via \type{\pdflastobj}. The object can later be filled +with contents by \Syntax{\Tex{\pdfobj} \Literal{useobjnum} +\Something{number} \Lbrace\Something{balanced text}\Rbrace}. +But the reserved object number can already be used before by other +objects, which provides a forward||referencing mechanism. + +The object is kept in memory and will be written to the \PDF\ output only +when its number is referred to by \type{\pdfrefobj} or when \type{\pdfobj} +is preceded by \type{\immediate}. Nothing is appended to the list being +built. The number of the most recently created object is accessible via +\type{\pdflastobj}. + +\pdftexprimitive{\Syntax{\Tex{\pdflastobj} \Whatever{read||only integer}}} +\bookmark{\tex{pdflastobj}} + +This command returns the object number of the last object created by \type +{\pdfobj}. + +\pdftexprimitive{\Syntax{\Tex{\pdfrefobj} \Something{object number} + \Modelist{h, v, m}}} +\bookmark{\tex{pdfrefobj}} + +This command appends a whatsit node to the list being built. When the whatsit +node is searched at shipout time, \PDFTEX\ will write the object +\Something{object number} +to the \PDF\ output if it has not been written yet. + +%*********************************************************************** + +\subsection{Page and pages objects} + +\pdftexprimitive{\Syntax{\Tex{\pdfpagesattr} \Whatever{tokens}}} +\bookmark{\tex{pdfpagesattr}} + +\PDFTEX\ expands this token list when it finishes the \PDF\ output and +adds the resulting character stream to the root \type{Pages} +object. When defined, these are applied to all pages in the +document. Some examples of attributes are \type{/CropBox}, the rectangle +specifying the region of the page being displayed and printed, and +\type{/Rotate}, the number of degrees (in multiples of 90) the page +should be rotated clockwise when it is displayed or printed. + +% /MediaBox is not a good example, since will never take effect + +\starttyping +\pdfpagesattr + { /Rotate 90 % rotate all pages by 90 degrees + /CropBox [0 0 612 792] } % the crop size of all pages (in bp) +\stoptyping + +\pdftexprimitive{\Syntax{\Tex{\pdfpageattr} \Whatever{tokens}}} +\bookmark{\tex{pdfpageattr}} + +This is similar to \type{\pdfpagesattr}, but has priority over it. +It can be used to override any attribute given by \type{\pdfpagesattr} +for an individual page. The token list is expanded when \PDFTEX\ ships out +a page. The contents are added to the attributes of the current page. + +If the \type{\pdfpageattr} value contains the string \type{/MediaBox}, +then \PDFTEX\ omits outputting its own \type{/MediaBox} value (which is +\type{[0 0 }\Something{\it page\_width} \Something{\it +page\_height}\type{]}). (This behavior was introduced in version +1.40.18.) + +\pdftexprimitive{\Syntax{\Tex{\pdfpageresources} \Whatever{tokens}}} +\bookmark{\tex{pdfpageresources}} + +These tokens are added to the resource dictionary for all pages, before +the font, XOBject, and other resources. + +\starttyping +\pdfpageresources{/MyPageResourceAttribute /MyValue} +\stoptyping + +\pdftexprimitive{\Syntax{\Tex{\pdfpageref} \Something{page number} + \Whatever{expandable}}} +\bookmark{\tex{pdfpageref}} + +This primitive expands to the number of the page object that contains +the dictionary for page \Something{page number}. If the page +\Something{page number} does not exist, a warning will be issued, +a fresh unused \PDF\ object will be generated, and \type{\pdfpageref} +will expand to that object number. + +\Eg, if the dictionary for page~5 of the \TEX\ document is contained in +\PDF\ object no.~18, \tex{pdfpageref5} expands to the number 18. + +%*********************************************************************** + +\subsection{Form XObjects} + +The next three primitives support a \PDF\ feature called \quote {object +reuse} in \PDFTEX. The idea is first to create a `form XObject' in +\PDF. The content of this object corresponds to the content of a \TEX\ +box; it can contain pictures and references to other form XObjects +as well. After creation, the form XObject can be used multiple times +by simply referring to its object number. This feature can be useful +for large documents with many similar elements, as it can reduce the +duplication of identical objects. + +These commands behave similarly to \type{\pdfobj}, \type{\pdfrefobj} +and \type{\pdflastobj}, but instead of taking raw \PDF\ code, they handle +text typeset by \TEX. + +\pdftexprimitive{\Syntax{\Tex{\pdfxform} \Optional{\Something{attr spec}} + \Optional{\Something{resources spec}} \Something{box number} + \Modelist{h, v, m}}} +\bookmark{\tex{pdfxform}} + +This command creates a form XObject corresponding to the contents of the +box \Something{box number}. The box can contain other raw objects, form +XObjects, or images as well. It can however {\em not} contain annotations +because they are laid out on a separate layer, are positioned absolutely, +and have dedicated housekeeping. \type{\pdfxform} makes the box void, +as \type{\box} does. + +When \Something{attr spec} is given, the text will be written +as additional attribute into the form XObject dictionary. The +\Something{resources spec} is similar, but the text will be added +to the resources dictionary of the form XObject. The text given by +\Something{attr spec} or \Something{resources spec} is written before +other entries of the form dictionary and|/|or the resources dictionary +and takes priority over later ones. + +\pdftexprimitive{\Syntax{\Tex{\pdfrefxform} \Something{object number} + \Modelist{h, v, m}}} +\bookmark{\tex{pdfrefxform}} + +The form XObject is kept in memory and will be written to the \PDF\ +output only when its object number is referred to by \type{\pdfrefxform} +or when \type{\pdfxform} is preceded by \type{\immediate}. Nothing is +appended to the list being built. The number of the most recently created +form XObject is accessible via \type{\pdflastxform}. + +When issued, \type{\pdfrefxform} appends a whatsit node to the list being +built. When the whatsit node is searched at shipout time, \PDFTEX\ will +write the form \Something{object number} to the \PDF\ output if it is +not written yet. + +\pdftexprimitive{\Syntax{\Tex{\pdflastxform} \Whatever{read||only integer}}} +\bookmark{\tex{pdflastxform}} + +The object number of the most recently created form XObject is accessible +via \type{\pdflastxform}. + +As said, this feature can be used for reusing information. This mechanism +also plays a role in typesetting fill||in forms. Such widgets sometimes +depends on visuals that show up on user request, but are hidden otherwise. + +\pdftexprimitive{\Syntax{\Tex{\pdfxformname} \Something{object number} + \Whatever{expandable}}} +\bookmark{\tex{pdfxformname}} + +In \PDF\ files produced by \PDFTEX\ one can recognize a form Xobject by +the prefix~\type{/Fm} followed by a number, for instance \type{/Fm2}. +For a given form XObject number, this primitive expands to the number in +the corresponding form XObject name. \Eg, if \type{/Fm2} corresponds to +some form XObject with object number 7, the \type{\pdfxformname7} +expands to the number~\type{2}. \introduced{1.30.0} + +%*********************************************************************** + +\subsection{Graphics inclusion} + +\PDF\ provides a mechanism for embedding graphic and textual objects: form +XObjects. In \PDFTEX\ this mechanism is accessed by means of \type{\pdfxform}, +\type{\pdflastxform} and \type{\pdfrefxform}. A special kind of XObjects +are bitmap graphics and for manipulating them similar commands are provided. + +\pdftexprimitive{\Syntax{\Tex{\pdfximage} + \Optional{\Something{rule spec}} + \Optional{\Something{attr spec}} + \Optional{\Something{page spec}} + \Optional{\Something{colorspace spec}} + \Optional{\Something{pdf box spec}} + \Something{general text} + \Modelist{h, v, m} +}} +\bookmark{\tex{pdfximage}} + +This command creates an image object. The dimensions of the image can be +controlled via \Something{rule spec}\unkern. The default values are zero +for depth and \quote {running} for height and width. If all of them are +given, the image will be scaled to fit the specified values. If some +(but not all) are given, the rest will be set to a value corresponding +to the remaining ones so as to make the image size to yield the same +proportion of $width : (height+depth)$ as the original image size, where +depth is treated as zero. If none are given then the image will take its +natural size. + +An image inserted at its natural size often has a resolution of \type +{\pdfimageresolution} (see below) given in dots per inch in the output +file, but some images may contain data specifying the image resolution, +and in such a case the image will be scaled to the correct +resolution. The dimensions of an image can be accessed by enclosing the +\type{\pdfrefximage} command to a box and checking the dimensions of the +box: + +\starttyping +\setbox0=\hbox{\pdfximage{somefile.png}\pdfrefximage\pdflastximage} +\stoptyping + +Now we can use \type{\wd0} and \type{\ht0} to question the natural size of +the image as determined by \PDFTEX. When dimensions are specified before the +\type{{somefile.png}}, the graphic is scaled to fit these. Note that, unlike +the \eg\ \type{\input} primitive, the filename is supplied between +braces. + +The image type is specified by the extension of the given file name: +\type{.png} stands for \PNG\ image, \type{.jpg} (or \type{.jpeg}) for +\JPEG, \type{.jbig2} (preferred, but \type{.jb2} works also) for \JBIGTWO, +and \type{.pdf} for \PDF\ file. But once \PDFTEX\ has opened the file, +it checks the file type first by looking to the magic number at the +file start, which gets precedence over the file name extension. This +gives a certain degree of fault tolerance, if the file name extension +is stated wrongly. + +Similarly to \type{\pdfxform}, the optional text given by \Something{attr +spec} will be written as additional attributes of the image before +other keys of the image dictionary. One should be aware, that slightly +different type of \PDF\ object is created while including \PNG, \JPEG, +or \JBIG2\ bitmaps and \PDF\ images. + +While working with \PDF\ or \JBIG2\ images, \Something{page spec} +allows to decide which page of the document is to be included; +the \Something{page spec} is irrelevant for the other two image +formats. Starting with \PDFTEX\ 1.11 one may also decide in the \PDF\ +image case, which page box of the image is to be treated as a final +bounding box. If \Something{pdf box spec} is present, it overrides the +default behavior specified by the \type{\pdfpagebox} parameter, and is +overridden by the (obsolete) \type{\pdfforcepagebox} parameter. This +option is irrelevant for non||\PDF\ inclusions. + +Starting with \PDFTEX\ 1.21, \type{\pdfximage} command supports +\type{colorspace} keyword followed by an object number (user||defined +colorspace for the image being included). This feature works for \JPEG\ +images only. \PNG s are \RGB\ palettes, \JBIG2 s are bitonal, and \PDF\ +images have always self||contained color space information. + +\pdftexprimitive{\Syntax{\Tex{\pdfrefximage} \Something{object number}}} +\bookmark{\tex{pdfrefximage}} + +The image is kept in memory and will be written to the \PDF\ output only when +its number is referred to by \type{\pdfrefximage} or \type{\pdfximage} is +preceded by \type{\immediate}. Nothing is appended to the list being built. + +\type{\pdfrefximage} appends a whatsit node to the list being built. When +the whatsit node is searched at shipout time, \PDFTEX\ will write the image +with number \Something{object number} to the \PDF\ output if it has not been +written yet. + +\pdftexprimitive{\Syntax{\Tex{\pdflastximage} \Whatever{read||only integer}}} +\bookmark{\tex{pdflastximage}} + +The number of the most recently created XObject image is accessible via \type +{\pdflastximage}. + +\pdftexprimitive{\Syntax{\Tex{\pdfximagebbox} \Something{integer} + \Something{integer} \Whatever{expandable}}} +\bookmark{\tex{pdfximagebbox}} + +The dimensions of the bounding box of a \PDF\ image loaded with +\type{\pdfximage} are stored in a table. This primitive returns those +dimensions as follows: + +\starttyping +\pdfximage{afile.pdf} +\pdfximagebbox\pdflastximage 1 % Returns lower-left x +\pdfximagebbox\pdflastximage 2 % Returns lower-left y +\pdfximagebbox\pdflastximage 3 % Returns upper-right x +\pdfximagebbox\pdflastximage 4 % Returns upper-right y +\stoptyping + +\pdftexprimitive{\Syntax{\Tex{\pdflastximagecolordepth} + \Whatever{read||only integer}}} +\bookmark{\tex{pdflastximagecolordepth}} + +The color depth (\type{1} for 1-bit images, \type{2} for 2-bit images, +and so on) of the last image accessed with \type{\pdfximage}. + +\pdftexprimitive{\Syntax{\Tex{\pdflastximagepages} + \Whatever{read||only integer}}} +\bookmark{\tex{pdflastximagepages}} + +This read||only register returns the highest page number from a file +previously accessed via the \type{\pdfximage} command. +This is useful only for \PDF\ files; it always returns \type{1} +for \PNG, \JPEG, or \JBIGTWO\ files. + +\pdftexprimitive{\Syntax{\Tex{\pdfimageresolution} \Whatever{integer}}} +\bookmark{\tex{pdfimageresolution}} + +The integer \type{\pdfimageresolution} parameter (unit: dots per +inch, dpi) is a last resort value, used only for bitmap (\JPEG, \PNG, +\JBIGTWO) images, but not for \PDF{}s. The priorities are as follows: +Often one image dimension (\type{width} or \type{height}) is stated +explicitly in the \TEX\ file. Then the image is properly scaled so +that the aspect ratio is kept. If both image dimensions are given, +the image will be stretched accordingly, whereby the aspect ratio might +get distorted. Only if no image dimension is given in the \TEX\ file, +the image size will be calculated from its width and height in pixels, +using the $x$ and $y$ resolution values normally contained in the image +file. If one of these resolution values is missing or weird (either +$<$~0 or $>$~65535), the \type{\pdfimageresolution} value will be used +for both $x$ and $y$ resolution, when calculating the image size. And +if the \type{\pdfimageresolution} is zero, finally a default resolution +of 72\,dpi would be taken. The \type{\pdfimageresolution} is read when +\PDFTEX\ creates an image via \type{\pdfximage}. The given value is +clipped to the range $0..65535$\,(dpi). + +Currently this parameter is used particularly for calculating the +dimensions of \JPEG\ images in \EXIF\ format (unless at least one +dimension is stated explicitly); the resolution values coming with +\EXIF\ files are currently ignored. + +\pdftexprimitive{\Syntax{\Tex{\pdfpagebox} \Whatever{integer}}} +\bookmark{\tex{pdfpagebox}} + +When \PDF\ files are included, the command \type{\pdfximage} allows the +selection of which \PDF\ page box to use in the optional field +\Something{image attr spec}\unkern. If the option isn't present, the +page box defaults to the value of \type{\pdfpagebox} as follows: +(1)~media box, (2)~crop box, (3)~bleed box, (4)~trim box, and +(5)~artbox. + +\pdftexprimitive{\Syntax{\Tex{\pdfforcepagebox} \Whatever{integer}}} +\bookmark{\tex{pdfforcepagebox}} + +%- It is now possible to specify the pdf page box to use when including pdfs. +% The syntax has been extended: +% \pdfximage [<image attr spec>] <general text> (h, v, m) +% <image attr spec> --> [<rule spec>] [<attr spec>] [<page spec>] [<pdf box spec>] +% <pdf box spec> --> mediabox|cropbox|bleedbox|trimbox|artbox +% The default is cropbox (which defaults to mediabox), to be compatible with +% previous versions of pdfTeX. +% The page box specified at \pdfximage can be globally overridden with the +% config parameter always_use_pdfpagebox and the command +% \pdfoptionalwaysusepdfpagebox <integer>, where 0 is the default (use +% whatever is specified with \pdfximage), 1 is media, 2 is crop, 3 is +% bleed, 4 is trim and 5 is artbox. This can only be set once per +% object, i.\,e.\ the value used at \pdfximage is remembered. +% See the PDF Reference for an explanation of the boxes. + +The integer primitive \type{\pdfforcepagebox} allows globally +overriding the choice of the page box used with \type{\pdfximage}. It +takes the same values as \type{\pdfpagebox}. The command is available +starting with \PDFTEX\ 1.30.0, as a shortened synonym of obsolete +\type{\pdfoptionalwaysusepdfpagebox} instruction, but is itself +now considered obsolete --- a mixture of \type{\pdfpagebox} and +\Something{image attr spec} is better. + +\pdftexprimitive{\Syntax{\Tex{\pdfinclusionerrorlevel} \Whatever{integer}}} +\bookmark{\tex{pdfinclusionerrorlevel}} + +This controls the behavior of \PDFTEX\ when a \PDF\ file is included +that has a newer version than the one specified by +\type{\pdfminorversion}. If \type{\pdfinclusionerrorlevel} is set to~0 +(the default), \PDFTEX\ gives only a warning; if 1, \PDFTEX\ raises an +error; if negative, no diagnostic at all is given. + +It was originally a shortened synonym of +\type{\pdfoptionpdfinclusionerrorlevel}, which is now obsolete. +\introduced{1.30.0} + +\pdftexprimitive{\Syntax{\Tex{\pdfimagehicolor} \Whatever{integer}}} +\bookmark{\tex{pdfimagehicolor}} + +This primitive, when set to~1, enables embedding of \PNG\ images with +16~bit wide color channels at their full color resolution. As such an +embedding mode is defined only from \PDF\ version~1.5 onwards, the +\type{\pdfimagehicolor} functionality is automatically disabled in +\PDFTEX\ if \type{\pdfminorversion}~$<$~5; then each 16~bit color +channel is reduced to a width of 8~bit by stripping the lower 8~bits +before embedding. The same stripping happens when +\type{\pdfimagehicolor} is set to~0. For \type{\pdfminorversion}~$\ge$~5 +the default value of \type{\pdfimagehicolor} is~1. If specified, the +parameter must appear before any data is written to the \PDF\ output. +\introduced{1.30.0} + +\pdftexprimitive{\Syntax{\Tex{\pdfimageapplygamma} \Whatever{integer}}} +\bookmark{\tex{pdfimageapplygamma}} + +This primitive, when set to~1, enables gamma correction while embedding +\PNG\ images, taking the values of the primitives \type{\pdfgamma} as +well as the gamma value embedded in the \PNG\ image into account. When +\type{\pdfimageapplygamma} is set to~0, no gamma correction is +performed. If specified, the parameter must appear before any data is +written to the \PDF\ output. \introduced{1.30.0} + +\pdftexprimitive{\Syntax{\Tex{\pdfgamma} \Whatever{integer}}} +\bookmark{\tex{pdfgamma}} + +This primitive defines the `device gamma' for \PDFTEX. Values are in +promilles (same as \type{\mag}). The default value of this primitive +is~1000, defining a device gamma value of~1.0. + +When \type{\pdfimageapplygamma} is set to~1, then whenever a \PNG\ image +is included, \PDFTEX\ applies a gamma correction. This correction is +based on the value of the \type{\pdfgamma} primitive and the `assumed +device gamma' that is derived from the value embedded in the actual +image. If no embedded value can be found in the \PNG\ image, then the +value of \type{\pdfimagegamma} is used instead. +If specified, the parameter must appear before any data is written to the +\PDF\ output. +\introduced{1.30.0} + +\pdftexprimitive{\Syntax{\Tex{\pdfimagegamma} \Whatever{integer}}} +\bookmark{\tex{pdfimagegamma}} + +This primitive gives a default `assumed gamma' value for \PNG\ images. +Values are in promilles (same as for \type{\pdfamma}). The default value +of this primitive is~2200, implying an assumed gamma value of~2.2. + +When \PDFTEX\ is applying gamma corrections, images that do not have an +embedded `assumed gamma' value are assumed to have been created for +a device with a gamma of 2.2. Experiments show that this default setting +is correct for a large number of images; however, if your images come +out too dark, you probably want to set \type{\pdfimagegamma} to a lower +value, like~1000. +If specified, the parameter must appear before any data is written to the +\PDF\ output. +\introduced{1.30.0} + +\pdftexprimitive{\Syntax{\Tex{\pdfpxdimen} \Whatever{dimen}}} +\bookmark{\tex{pdfpxdimen}} + +While working with bitmap graphics or typesetting electronic documents, +it might be convenient to base dimensions on pixels rather than \TeX's +standard units like \type{pt} or \type{em}. For this purpose, \PDFTEX\ +provides an extra unit called \type{px} that takes the dimension given to +the \type{\pdfpxdimen} primitive. In example, to make the unit \type{px} +corresponding to 96\,dpi pixel density (then 1\,px~=~72/96\,bp), one +can do the following calculation: + +\starttyping +\pdfpxdimen=1in % 1 dpi +\divide\pdfpxdimen by 96 % 96 dpi +\hsize=1200px +\stoptyping + +Then \type{\hsize} amounts to 1200~pixels in 96\,dpi, which is +exactly 903.375\,pt (but \TeX\ rounds it to 903.36914\,pt). The +default value of \type{\pdfpxdimen} is 1\,bp, corresponding to a pixel +density of 72\,dpi. This primitive is completely independent from the +\type{\pdfimageresolution} and \type{\pdfpkresolution} parameters. +\introduced{1.30.0} It used to be an integer register that gave +the dimension 1\,px as number of scaled points, defaulting to 65536 +(1\,px equal to 65536\,sp~$=$~1\,pt). Starting with \PDFTEX\ 1.40.0, +\type{\pdfpxdimen} is now a real dimension parameter. + +\pdftexprimitive{\Syntax{\Tex{\pdfinclusioncopyfonts} \Whatever{integer}}} +\bookmark{\tex{pdfinclusioncopyfonts}} + +If positive, this parameter forces \PDFTEX\ to include fonts from a \PDF\ +file loaded with \type{\pdfximage}, even if those fonts are available on +disk. Bigger files might be created, but included \PDF\ files are sure to +be embedded with the adequate fonts; indeed, the fonts on disk might be +different from the embedded ones, and glyphs might be missing. + +\pdftexprimitive{\Syntax{\Tex{\pdfsuppresswarningpagegroup} + \Whatever{integer}}} +\bookmark{\tex{pdfsuppresswarningpagegroup}} + +Ordinarily, \PDFTEX\ gives a warning when more than one included \PDF\ +file has a so-called ``page group object'' (\type{/Group}), because only +one can ``win'' --- that is, be propagated to the page level. Usually +the page groups are identical, but when they are not, the result is +unpredictable. It would be ideal if \PDFTEX\ in fact detected whether +the page groups were the same and only gave the warning in the +problematic case; unfortunately, this is not easy (a patch would be +welcome). Nevertheless, often one observes that there is no actual +problem. Then seeing the warnings on every run is just noise, and can +be suppressed by setting this parameter to a positive number. +\introduced{1.40.15} + +%*********************************************************************** + +\subsection{Annotations} + +\PDF\ 1.4 provides four basic kinds of annotations: + +\startitemize[packed] +\item hyperlinks, general navigation +\item text clips (notes) +\item movies +\item sound fragments +\stopitemize + +The first type differs from the other three in that there is a designated +area involved on which one can click, or when moved over some action occurs. +\PDFTEX\ is able to calculate this area, as we will see later. All +annotations can be supported using the next two general annotation +primitives. + +\pdftexprimitive{\Syntax{\Tex{\pdfannot} \Something{annot type spec} + \Modelist{h, v, m}}} +\bookmark{\tex{pdfannot}} + +This command appends a whatsit node corresponding to an annotation to +the list being built. The dimensions of the annotation can be controlled +via the \Something{rule spec}. The default values are running for all +width, height and depth. When an annotation is written out, running +dimensions will take the corresponding values from the box containing +the whatsit node representing the annotation. The \Something{general +text} is inserted as raw \PDF\ code to the contents of annotation. The +annotation is written out only if the corresponding whatsit node is +searched at shipout time. + +\pdftexprimitive{\Syntax{\Tex{\pdflastannot} \Whatever{read||only integer}}} +\bookmark{\tex{pdflastannot}} + +This primitive returns the object number of the last annotation created by +\type{\pdfannot}. These two primitives allow users to create any annotation +that cannot be created by \type{\pdfstartlink} (see below). + +%*********************************************************************** + +\subsection[linking]{Destinations and links} + +The first type of annotation, mentioned above, is implemented by three +primitives. The first one is used to define a specific location as being +referred to. This location is tied to the page, not the exact location on the +page. The main reason for this is that \PDF\ maintains a dedicated list of +these annotations |<|and some more when optimized|>| for the sole purpose of +speed. + +\pdftexprimitive{\Syntax{\Tex{\pdfdest} \Something{dest spec} + \Modelist{h, v, m}}} +\bookmark{\tex{pdfdest}} + +This primitive appends a whatsit node which establishes a destination +for links and bookmark outlines; the link is identified by either +a number or a symbolic name, and the way the viewer is to display the +page must be specified in \Something{dest type}\unkern, which must be +one of those mentioned in \in{table}[appearance]. + +\startbuffer +\starttabulate[|l|l|] +\HL +\NC \bf keyword \NC \bf meaning \NC\NR +\HL +\NC \tt fit \NC fit the page in the window \NC\NR +\NC \tt fith \NC fit the width of the page \NC\NR +\NC \tt fitv \NC fit the height of the page \NC\NR +\NC \tt fitb \NC fit the \quote{Bounding Box} of the page \NC\NR +\NC \tt fitbh \NC fit the width of \quote{Bounding Box} of the page \NC\NR +\NC \tt fitbv \NC fit the height of \quote{Bounding Box} of the page \NC\NR +\NC \tt xyz \NC goto the current position (see below) \NC\NR +\HL +\stoptabulate +\stopbuffer + +\placetable + [here][appearance] + {Options for display of outline and destinations.} + {\getbuffer} + +The specification \Literal{xyz} can optionally be followed by \Literal +{zoom} \Something{integer} to provide a fixed zoom||in. The \Something +{integer} is processed like \TEX\ magnification, i.\,e.\ 1000 is the +normal page view. When \Literal{zoom} \Something{integer} is given, +the zoom factor changes to 0.001 of the \Something{integer} value, +otherwise the current zoom factor is kept unchanged. + +The destination is written out only if the corresponding whatsit node is +searched at shipout time. + +\pdftexprimitive{\Syntax{\Tex{\pdfstartlink} + \Optional{\Something{rule spec}} + \Optional{\Something{attr spec}} + \Something{action spec} + \Modelist{h, m} +}} +\bookmark{\tex{pdfstartlink}} + +This primitive is used along with \type{\pdfendlink} and appends +a whatsit node corresponding to the start of a hyperlink. The whatsit +node representing the end of the hyperlink is created by +\type{\pdfendlink}. The dimensions of the link are handled in the +similar way as in \type{\pdfannot}. Both \type{\pdfstartlink} and +\type{\pdfendlink} must be in the same level of box nesting. A hyperlink +with running width can be multi||line or even multi||page, in which case +all horizontal boxes with the same nesting level as the boxes containing +\type{\pdfstartlink} and \type{\pdfendlink} will be treated as part of +the hyperlink. The hyperlink is written out only if the corresponding +whatsit node is searched at shipout time. + +Additional attributes, which are explained in great detail in the +\PDFReference, can be given via \Something{attr spec}\unkern. Typically, +the attributes specify the color and thickness of any border around +the link. Thus \typ {/C [0.9 0 0] /Border [0 0 2]} specifies a color +(in \RGB) of dark red, and a border thickness of 2~points. + +While all graphics and text in a \PDF\ document have relative positions, +annotations have internally hard||coded absolute positions. Again this +is for the sake of speed optimization. The main disadvantage is that these +annotations do {\em not} obey transformations issued by \type +{\pdfliteral}'s. + +The \Something{action spec} specifies the action that should be performed +when the hyperlink is activated while the \Something{user-action spec} +performs a user||defined action. A typical use of the latter is to specify +a \URL, like \typ {/S /URI /URI (http://www.tug.org/)}, or a named action like +\typ {/S /Named /N /NextPage}. + +A \Something{goto-action spec} performs a GoTo action. Here \Something +{numid} and \Something{nameid} specify the destination identifier (see +below). The \Something{page spec} specifies the page number of the +destination, in this case the zoom factor is given by \Something{general +text}\unkern. A destination can be performed in another \PDF\ file by +specifying \Something{file spec}\unkern, in which case +\Something{newwindow spec} specifies whether the file should be opened +in a new window. A \Something{file spec} can be either a \type{(string)} +or a \type{<<dictionary>>}. The default behavior of the +\Something{newwindow spec} depends on the browser setting. + +A \Something{thread-action spec} performs an article thread reading. The +thread identifier is similar to the destination identifier. A thread can be +performed in another \PDF\ file by specifying a \Something{file spec}\unkern. + +\pdftexprimitive{\Syntax{\Tex{\pdfendlink} \Modelist{h, m}}} +\bookmark{\tex{pdfendlink}} + +This primitive ends a link started with \type{\pdfstartlink}. All text +between \type{\pdfstartlink} and \type{\pdfendlink} will be treated as part +of this link. \PDFTEX\ may break the result across lines (or pages), in which +case it will make several links with the same content. + +\pdftexprimitive{\Syntax{\Tex{\pdflastlink} \Whatever{read||only integer}}} +\bookmark{\tex{pdflastlink}} + +This primitive returns the object number of the last link created by +\type{\pdfstartlink} (analogous to \type{\pdflastannot}). +\introduced{1.40.0} + +\pdftexprimitive{\Syntax{\Tex{\pdflinkmargin} \Whatever{dimen}}} +\bookmark{\tex{pdflinkmargin}} + +This dimension parameter specifies the margin of the box representing +a hyperlink and is read when a page containing hyperlinks is shipped out. + +\pdftexprimitive{\Syntax{\Tex{\pdfdestmargin} \Whatever{dimen}}} +\bookmark{\tex{pdfdestmargin}} + +Margin added to the dimensions of the rectangle around the destinations. + +\pdftexprimitive{\Syntax{\Tex{\pdfsuppresswarningdupdest} \Whatever{integer}}} +\bookmark{\tex{pdfsuppresswarningdupdest}} + +Ordinarily, \PDFTEX\ gives a warning when the same destination is used +more than once. However, due to problematic macro packages, sometimes a +document may end up producing the warning through no fault of its own, +and fixing the macros may well not be trivial. Then seeing the warnings +on every run is just noise, and can be suppressed by setting this +parameter to a positive number. \introduced{1.40.13} + +%*********************************************************************** + +\subsection{Bookmarks} + +\pdftexprimitive{\Syntax{\Tex{\pdfoutline} + \Optional{\Something{attr spec}} + \Something{action spec} + \Optional{\Literal{count} \Something{integer}} + \Something{general text} + \Modelist{h, v, m} +}} +\bookmark{\tex{pdfoutline}} + +This primitive creates an outline (or bookmark) entry. The first parameter +specifies the action to be taken, and is the same as that allowed for \type +{\pdfstartlink}. The \Something{count} specifies the number of direct +subentries under this entry; specify~0 or omit it if this entry has no +subentries. If the number is negative, then all subentries will be closed and +the absolute value of this number specifies the number of subentries. The +\Something{text} is what will be shown in the outline window. Note that this +is limited to characters in the \PDF\ Document Encoding vector. The outline +is written to the \PDF\ output immediately. + +%*********************************************************************** + +\subsection{Article threads} + +\pdftexprimitive{\Syntax{\Tex{\pdfthread} \Optional{\Something{rule spec}} + \Optional{\Something{attr spec}} \Something{id spec} \Modelist{h, v, m}}} +\bookmark{\tex{pdfthread}} + +Defines a bead within an article thread. Thread beads with same +identifiers (spread across the document) will be joined together. + +\pdftexprimitive{\Syntax{\Tex{\pdftstartthread} + \Optional{\Something{rule spec}} + \Optional{\Something{attr spec}} + \Something{id spec} \Modelist{v, m}}} +\bookmark{\tex{pdfstartthread}} + +This uses the same syntax as \type{\pdfthread}, apart that it must be +followed by a \type{\pdfendthread}. \type{\pdfstartthread} and the +corresponding \type{\pdfendthread} must end up in vboxes with the same +nesting level; all vboxes between them will be added into the thread. +Note that during output runtime if there are other newly created +boxes which have the same nesting level as the vbox/vboxes containing +\type{\pdfstartthread} and \type{\pdfendthread}, they will be also added +into the thread, which is probably not what you want. To avoid such +unconsidered behavior, it's often enough to wrap boxes that shouldn't +belong to the thread by a box to change their box nesting level. + +\pdftexprimitive{\Syntax{\Tex{\pdfendthread} \Modelist{v, m}}} +\bookmark{\tex{pdfendthread}} + +This ends an article thread started before by \type{\pdfstartthread}. + +\pdftexprimitive{\Syntax{\Tex{\pdfthreadmargin} \Whatever{dimen}}} +\bookmark{\tex{pdfthreadmargin}} + +Specifies a margin to be added to the dimensions of a bead within +an article thread. + +%*********************************************************************** + +\subsection{Literals and specials} + +\pdftexprimitive{\Syntax{\Tex{\pdfliteral} + \Optional{\Something{pdfliteral spec}} + \Something{general text} + \Modelist{h, v, m} + }} +\bookmark{\tex{pdfliteral}} + +Like \type{\special} in normal \TEX, this command inserts raw +\PDF\ code into the output. This allows support of color and text +transformation. This primitive is heavily used in the \METAPOST\ +inclusion macros. Normally \PDFTEX\ ends a text section in the \PDF\ +output and sets the transformation matrix to the current location on the +page before inserting \Something{general text}\unkern, however this can be +turned off by giving the optional keyword \Literal{direct}. This command +appends a whatsit node to the list being built. \Something{general text} +is expanded when the whatsit node is created and not when it is shipped +out, as with \type{\special}. + +Starting with version 1.30.0, \PDFTEX\ allows to use a new keyword +\type{page} instead of \type{direct}. Both modify the default behavior +of \type{\pdfliteral}, avoiding translation of the coordinates space +before inserting the literal code. The difference is that the \type{page} +keyword instructs \PDFTEX\ to close a \type{BT ET} text block before +inserting anything. It means that the literal code inserted refers to the +origin (lower||left corner of the page) and can be safely enclosed with +\type{q Q}. Note, that in most cases using \type{q Q} operators inside +\type{\pdfliteral} with \type{direct} keyword will produce corrupted +\PDF\ output, as the \PDF\ standard doesn't allow to do anything like +this within a \type{BT ET} block. + +% HE: \unkern is a kludge here; wanted to have tight "{pdf:" +\pdftexprimitive{\Syntax{\Tex{\special} \Lbrace\unkern\Literal{pdf:} + \Something{text} \Rbrace}} +\bookmark{\tex{special}} + +This is equivalent to \Syntax{\Tex{\pdfliteral} \Lbrace \Something{text} +\Rbrace}. + +\pdftexprimitive{\Syntax{\Tex{\special} \Lbrace\unkern\Literal{pdf:direct:} + \Something{text} \Rbrace}} +\bookmark{\tex{special\ direct}} + +This is equivalent to \Syntax{\Tex{\pdfliteral} \Literal{direct} \Lbrace +\Something{text} \Rbrace}. + +\pdftexprimitive{\Syntax{\Tex{\special} \Lbrace\unkern\Literal{pdf:page:} + \Something{text} \Rbrace}} +\bookmark{\tex{special\ page}} + +This is equivalent to \Syntax{\Tex{\pdfliteral} \Literal{page} \Lbrace +\Something{text} \Rbrace}. + +%*********************************************************************** + +\subsection{Strings} + +\pdftexprimitive{\Syntax{\Tex{\pdfescapestring} \Something{general text} + \Whatever{expandable}}} +\bookmark{\tex{pdfescapestring}} + +Starting with version 1.30.0, \PDFTEX\ provides a mechanism for converting +a general text into \PDF\ string. Many characters that may be needed inside +such a text (especially parenthesis), have a special meaning inside a \PDF\ +string object and thus, can't be used literally. The primitive replaces each +special \PDF\ character by its literal representation by inserting a backslash +before that character. Some characters (\eg\ space) are also converted into +3||digit octal number. In example, \type{\pdfescapestring{Text (1)}} will be +expanded to \type{Text\040\(1\)}. This ensures a literal interpretation of the +text by the \PDF\ viewer. +\introduced{1.30.0} + +\pdftexprimitive{\Syntax{\Tex{\pdfescapename} \Something{general text} + \Whatever{expandable}}} +\bookmark{\tex{pdfescapename}} + +In analogy to \type{\pdfescapestring}, \type{\pdfescapename} replaces each +special \PDF\ character inside the general text by its hexadecimal +representation preceded by \type{#} character. This ensures the proper +interpretation of the text if used as a \PDF\ name object. In example, +\type{Text (1)} will be replaced by \type{Text#20#281#29}. +\introduced{1.30.0} + +\pdftexprimitive{\Syntax{\Tex{\pdfescapehex} \Something{general text} + \Whatever{expandable}}} +\bookmark{\tex{pdfescapehex}} + +This command converts each character of \Something{general text} into its +hexadecimal representation. Each character of the argument becomes a pair of +hexadecimal digits. \introduced{1.30.0} + +\pdftexprimitive{\Syntax{\Tex{\pdfunescapehex} \Something{general text} + \Whatever{expandable}}} +\bookmark{\tex{pdfunescapehex}} + +This command treats each character pair of \Something{general text} as +a hexadecimal number and returns an \ASCII\ character of this code. +\introduced{1.30.0} + +\pdftexprimitive{\Syntax{\Tex{\pdfstrcmp} \Something{general text} + \Something{general text} \Whatever{expandable}}} +\bookmark{\tex{pdfstrcmp}} + +This command compares two strings and expands to \type{0} if the strings +are equal, to \type{-1} if the first string ranks before the second, and +to \type{1} otherwise. \introduced{1.30.0} + +\pdftexprimitive{\Syntax{\Tex{\pdfmatch} \Optional{\Literal{icase}} + \Optional{\Literal{subcount} \Something{integer}} \Something{general text} + \Something{general text} \Whatever{expandable}}} +\bookmark{\tex{pdfmatch}} + +This command implements pattern matching (using the syntax of \POSIX\ +extended regular expressions). The first \Something{general text} is a +pattern and the second is a string. The command expands to \type{-1} if +the pattern is invalid, to \type{0} if no match is found, and to +\type{1} if a match is found. With the \type{icase} option, the matching +is case-insensitive. The \type{subcount} option sets the size of the +table storing the found (sub)patterns; its default is 10. +\introduced{1.30.0} + +\pdftexprimitive{\Syntax{\Tex{\pdflastmatch} \Something{integer} + \Whatever{expandable}}} +\bookmark{\tex{pdflastmatch}} + +The matches found with \type{\pdfmatch} are stored in a table. This +command returns the entry for \Something{integer}, in the format +\Something{position}\type{->}\Something{string}; \Something{position} is +the position of the match (starting at zero) or \type{-1} if no match +was found, and \Something{string} is the matched substring. + +Entry~0 contains the match as a whole; the subsequent entries contain +submatches corresponding to the subpatterns, up to \type{subcount-1}. + +If \Something{integer} is less than zero, an error is given. + +For instance: + +\starttyping +\pdfmatch subcount 3 {ab(cd)*ef(gh)(ij)}{abefghij} +\pdflastmatch0 % "0->abefghij" +\pdflastmatch1 % "-1->" +\pdflastmatch2 % "4->gh" +\pdflastmatch3 % "-1->" +\stoptyping + +Entry~1 is empty because no match was found for \type{cd}, and entry~3 +is empty because it exceeds the table's size as set by \type{subcount}. +\introduced{1.30.0} + +%*********************************************************************** + +\subsection{Numbers} + +\pdftexprimitive{\Syntax{\Tex{\ifpdfabsnum} \Whatever{expandable}}} +\bookmark{\tex{ifpdfabsnum}} + +This conditional works like the standard \type{\ifnum}, except that it +compares absolute values of numbers. Although it seems to be a trivial +shortcut for a couple of \type{\ifnum x<0} tests, as a primitive it is +considerably more friendly in usage and works a bit faster. +\introduced{1.40.0} + +\pdftexprimitive{\Syntax{\Tex{\ifpdfabsdim} \Whatever{expandable}}} +\bookmark{\tex{ifpdfabsdim}} + +Analogous to \type{\ifpdfabsnum}, this conditional works like +\type{\ifdim}, except that it compares absolute values of +dimensions. \introduced{1.40.0} + +\pdftexprimitive{\Syntax{\Tex{\pdfuniformdeviate} \Something{number} + \Whatever{expandable}}} +\bookmark{\tex{pdfuniformdeviate}} + +Generate a uniformly-distributed random integer value between 0 +(inclusive) and \Something{number} (exclusive). This primitive expands +to a list of tokens. \introduced{1.30.0} + +\pdftexprimitive{\Syntax{\Tex{\pdfnormaldeviate} \Whatever{expandable}}} +\bookmark{\tex{pdfnormaldeviate}} + +Generate a normally-distributed random integer with a mean of~0 and +standard deviation 65\,536. That is, about 68\% of the time, the result +will be between $-65536$ and $65536$ (one standard deviation away from +the mean). About 95\% of results will be within two standard +deviations, and 99.7\% within three. This primitive expands to a list +of tokens. \introduced{1.30.0} + +\pdftexprimitive{\Syntax{\Tex{\pdfrandomseed} \Whatever{read||only integer}}} +\bookmark{\tex{pdfrandomseed}} + +You can use \type{\the\pdfrandomseed} to query the current seed value, +so you can \eg\ write the value to the log file. The initial value of +the seed is derived from the system time, and is not more than +1\,000\,999\,999 (this ensures that the value can be used with commands +like \type{\count}). \introduced{1.30.0} + +\pdftexprimitive{\Syntax{\Tex{\pdfsetrandomseed} \Something{number}}} +\bookmark{\tex{pdfsetrandomseed}} + +Set the random seed (\type{\pdfrandomseed}) to a specific value, +allowing you to replay sequences of semi-randoms at a later moment. +\introduced{1.30.0} + +%*********************************************************************** + +\subsection{Timekeeping} + +\pdftexprimitive{\Syntax{\Tex{\pdfelapsedtime} \Whatever{read||only integer}}} +\bookmark{\tex{pdfelapsedtime}} + +Return a number that represents the time elapsed from the moment of the +start of the run. The elapsed time is returned in `scaled seconds', +meaning seconds divided by 65536, \eg\ \PDFTEX\ has run for +\the\pdfelapsedtime\ `scaled seconds' when this paragraph was +typeset. Of course, the command will never return a value greater than +the highest number available in \TeX: if the time exceeds 32767 seconds, +the constant value $2^{31}-1$ will be returned. \introduced{1.30.0} + +\pdftexprimitive{\Syntax{\Tex{\pdfresettimer}}} +\bookmark{\tex{pdfresettimer}} + +Reset the internal timer so that \type{\pdfelapsedtime} +starts returning micro||time from~0 again. \introduced{1.30.0} + +%*********************************************************************** + +\subsection{Files} + +\pdftexprimitive{\Syntax{\Tex{\pdffilemoddate} \Something{general text} + \Whatever{expandable}}} +\bookmark{\tex{pdffilemoddate}} + +Expands to the modification date of file \Something{general text} in the same +format as for \type{\pdfcreationdate}, \eg\ it's {\tt \pdffilemoddate +{./pdftex-t.tex}} for the source of this manual. +\introduced{1.30.0} + +\pdftexprimitive{\Syntax{\Tex{\pdffilesize} \Something{general text} + \Whatever{expandable}}} +\bookmark{\tex{pdffilesize}} + +Expands to the size of file \Something{general text}, \eg\ it's {\tt +\pdffilesize {./pdftex-t.tex}} for the source of this manual. +\introduced{1.30.0} + +\pdftexprimitive{\Syntax{\Tex{\pdfmdfivesum} file \Something{general text} + \Whatever{expandable}}} +\bookmark{\tex{pdfmdfivesum\ file}} + +Expands to the \MDFIVE\ of file \Something{general text} in uppercase +hexadecimal format (same as \type{\pdfescapehex}), \eg\ it's {\tt +\pdfmdfivesum file {./pdftex-t.tex}} for the source of this manual. +\introduced{1.30.0} + +\pdftexprimitive{\Syntax{\Tex{\pdffiledump} \Optional{\Literal{offset} + \Something{number}} \Optional{\Literal{length} + \Something{number}} \Something{general text} \Whatever{expandable}}} +\bookmark{\tex{pdffiledump}} + +Expands to the dump of the file \Something{general text} in uppercase +hexadecimal format (same as \type{\pdfescapehex}), starting at offset +\Something{number} or 0 with length \Something{number}, if given. The first ten +bytes of the source of this manual are {\tt \pdffiledump length 10 +{./pdftex-t.tex}}. \introduced{1.30.0} + +%*********************************************************************** + +\subsection{Color stack} + +\PDFTEX\ 1.40.0 comes with color stack support (actually any graphic state +stack). + +\pdftexprimitive{\Syntax{\Tex{\pdfcolorstackinit} \Optional{\Literal{page}} + \Optional{\Literal{direct}} \Something{general text} \Whatever{expandable}}} +\bookmark{\tex{pdfcolorstackinit}} + +The primitive initializes a new graphic stack and returns its number. Optional +\Literal{page} keyword instructs \PDFTEX\ to restore the graphic at the +beginning of every new page. Also optional \Literal{direct} has the same effect +as for \Tex{\pdfliteral} primitive. \introduced{1.40.0} + +\pdftexprimitive{\Syntax{\Tex{\pdfcolorstack} \Something{stack number} + \Something{stack action} \Something{general text}}} +\bookmark{\tex{pdfcolorstack}} + +The command operates on the stack of a given number. If \Something{stack +action} is \Literal{push} keyword, the new value provided as +\Something{general text} is inserted into the top of the graphic stack +and becomes the current stack value. If followed by \Literal{pop}, the +top value is removed from the stack and the new top value becomes the +current. \Literal{set} keyword replaces the current value with +\Something{general text} without changing the stack size. +\Literal{current} keyword instructs just to use the current stack value +without modifying the stack at all. \introduced{1.40.0} + +\subsection{Transformations} + +Since the content of \Tex{\pdfliteral} is not interpreted anyhow, any +transformation inserted directly into the content stream, as well as saving +and restoring the current transformation matrix, remains unnoticed by +\PDFTEX\ positioning mechanism. As a consequence, links and other annotations +(that are formed in \PDF\ as different layer then the page content) are not +affected by such user-defined transformations. \PDFTEX\ 1.40.0 solves this +problem with three new primitives. + +\pdftexprimitive{\Syntax{\Tex{\pdfsetmatrix}}} +\bookmark{\tex{pdfsetmatrix}} + +Afine transformations are normally expressed with six numbers. First +four (no unit) values defining scaling, rotating and skewing, plus two +extra dimensions for shifting. Since the translation is handled by \TeX\ +itself, \Tex{\pdfsetmatrix} primitive expects as an argument a string +containing just the first four numbers of the transformation separated +by a space and assumes two position coordinates to be~0. In example, +\type{\pdfsetmatrix{0.87 -0.5 0.5 0.87}} rotates the current space by 30 +degrees, inserting \type{0.87 -0.5 0.5 0.87 0 0 cm} into the content +stream. \introduced{1.40.0} + +\pdftexprimitive{\Syntax{\Tex{\pdfsave}}} +\bookmark{\tex{pdfsave}} + +The command saves the current transformation by inserting \type{q} +operator into the content stream. \introduced{1.40.0} + +\pdftexprimitive{\Syntax{\Tex{\pdfrestore}}} +\bookmark{\tex{pdfrestore}} + +The command restores previously saved transformation by inserting \type{Q} +operator into the content stream. One should keep in mind that \Tex{\pdfsave} +and \Tex{\pdfrestore} pairs should always be properly nested and should start +and end at the same group level. \introduced{1.40.0} + +%*********************************************************************** + +\subsection{Miscellaneous} + +\pdftexprimitive{\Syntax{\tex {ifincsname} \Whatever{expandable}}} +\bookmark{\tex{ifincsname}} + +This conditional is true if evaluated inside \type{\csname ... \endcsname}, +and false otherwise. + + +\pdftexprimitive{\Syntax{\tex {ifpdfprimitive} \Something{control sequence} + \Whatever{expandable}}} +\bookmark{\tex{ifpdfprimitive}} + +This condition checks if the following control sequence has its +primitive meaning. If it has, \type{\ifpdfprimitive} returns true. In +any other case (redefined, made \type{\undefined}, has never been +primitive) false is returned. \introduced{1.40.0} + + +\pdftexprimitive{\Syntax{\Tex{\pdfcreationdate} \Whatever{expandable}}} +\bookmark{\tex{pdfcreationdate}} + +Expands to the date string \PDFTEX\ uses in the info dictionary of the +document, \eg\ for this file {\tt\pdfcreationdate}. \introduced{1.30.0} + + +\pdftexprimitive{\Syntax{\tex {pdfdraftmode} \Whatever{integer}}} +\bookmark{\tex{pdfdraftmode}} + +When set to 1 (or set by the command-line switch \type{-draftmode}) +\PDFTEX\ doesn't write the output \PDF\ file and doesn't actually read any +images but does everything else (including writing auxiliary files), +thus speeding up compilations when you know you need an extra run but +don't care about the output, \eg\ just to get the \BIBTEX\ references +right. \introduced{1.40.0} + + +\pdftexprimitive{\Syntax{\Tex{\pdfinsertht} \Something{integer} + \Whatever{expandable}}} +\bookmark{\tex{pdfinsertht}} + +If \Something{integer} is the number of an insertion class, this command +returns the height of the corresponding box at the current time. +For instance, the following returns \type{12pt} in plain \TEX: + +\starttyping +Abc\footnote*{Whatever.}\par +\pdfinsertht\footins +\stoptyping + + +\pdftexprimitive{\Syntax{\Tex{\pdflastxpos} \Whatever{read||only integer}}} +\bookmark{\tex{pdflastxpos}} + +This primitive returns an integer number representing the absolute $x$ +coordinate of the last point marked by \type{\pdfsavepos}. The unit is +`scaled points' (sp). + + +\pdftexprimitive{\Syntax{\Tex{\pdflastypos} \Whatever{read||only integer}}} +\bookmark{\tex{pdflastypos}} + +Completely analogous to \type{\pdflastxpos}, returning the $y$ coordinate. + + +\pdftexprimitive{\Syntax{\tex {pdfprimitive} \Something{control sequence}}} +\bookmark{\tex{pdfprimitive}} + +This command executes the primitive meaning of the following control +sequence, regardless of whether the control sequence has been redefined +or made undefined. If the primitive was expandable, \type{\pdfprimitive} +expands also. On the other hand, if the following control sequence never +was a primitive, nothing happens and no error is raised. (In some +versions of \PDFTEX\ prior to 1.40.19, an error was wrongly given.) +\introduced{1.40.0} + + +\pdftexprimitive{\Syntax{\Tex{\pdfretval} \Whatever{read||only integer}}} +\bookmark{\tex{pdfretval}} + +Set to $-1$ if \type{\pdfobj} ignores an invalid object number. Perhaps +this will be used to store the error status of other primitives in the +future. + + +\pdftexprimitive{\Syntax{\Tex{\pdfsavepos} \Modelist{h, v, m}}} +\bookmark{\tex{pdfsavepos}} + +This primitive marks the current absolute ($x,y$) position on the +media, with the reference point in the lower left corner. It is active +only during page shipout, when the page is finally assembled. The +position coordinates can then be retrieved by the \type{\pdflastxpos} +and \type{\pdflastypos} primitives, and \eg\ written out to some +auxiliary file. The coordinates can be used only after the current +\type{\shipout} has been finalized, therefore normally two \PDFTEX\ +runs are required to utilize these primitives. Starting with +\PDFTEX\ 1.40.0, this mechanism can be used also while running +in \DVI\ mode. + + +\pdftexprimitive{\Syntax{\Tex{\pdfshellescape} \Whatever{read||only integer}}} +\bookmark{\tex{pdfshellescape}} + +This primitive is~1 if \type{\write18} is enabled, 2 if it is +restricted, and 0 otherwise. (\type{\write18} was +\ifnum\pdfshellescape=0\relax not \fi enabled when this manual was +typeset.) \introduced{1.30.0} + + +\pdftexprimitive{\Syntax{\Tex{\pdftexbanner} \Whatever{expandable}}} +\bookmark{\tex{pdftexbanner}} + +Returns the \PDFTEX\ banner message, \eg\ for the version used here: +{\tt \pdftexbanner}. \introduced{1.20a} + + +\pdftexprimitive{\Syntax{\Tex{\pdftexrevision} \Whatever{expandable}}} +\bookmark{\tex{pdftexrevision}} + +\def\versplit#1#2#3{#1.#2#3} + +Returns the revision number of \PDFTEX, \eg\ for \PDFTEX\ version +\expandafter\versplit\the\pdftexversion.\pdftexrevision\ (used to produce +this document), it returns the number {\tt \pdftexrevision}. + + +\pdftexprimitive{\Syntax{\Tex{\pdftexversion} \Whatever{read||only integer}}} +\bookmark{\tex{pdftexversion}} + +Returns the version of \PDFTEX\ multiplied by 100, \eg\ for \PDFTEX\ +version \expandafter\versplit\the\pdftexversion.\pdftexrevision\ used to +produce this document, it returns {\tt \number\pdftexversion}. + + +\pdftexprimitive{\Syntax{\Tex{\quitvmode}}} +\bookmark{\tex{quitvmode}} + +The primitive instructs \PDFTEX\ to quit vertical mode and start +typesetting a paragraph. \type{\quitvmode} has the same effect as +\type{\leavevmode} definition from \type{plain} macro package. Note +however, that \type{\leavevmode} may conflict with \type{\everypar} +tokens list. No such risk while using \type{\quitvmode} instead. +\introduced{1.21a} + + +\pdftexprimitive{\Syntax{\Tex{\vadjust} + \Optional{\Something{pre spec}} + \Something{filler} + \Lbrace \Something{vertical mode material} \Rbrace + \Modelist{h, m} +}} +\bookmark{\tex{vadjust}} + +The \type{\vadjust} implementation of \PDFTEX\ adds an optional +qualifier \Something{pre spec}, which is simply the string \type{pre}, to +the original \TEX\ primitive with the same name. If +no \type{pre} is given, \type{\vadjust} behaves exactly as the original +(see the \TEX book, p.~281): it appends an adjustment item created +from \Something{vertical mode material} to the current list {\em after} +the line in which \type{\vadjust} appears. However, with the qualifier +\type{pre}, the adjustment item is put {\em before} the line in which +\type{\vadjust pre} appears. + +%*********************************************************************** + +\section{Graphics} + +\PDFTEX\ supports inclusion of pictures in \PNG, \JPEG, \JBIGTWO, and +\PDF\ format; a few differences between these are discussed below. The +most common technique with \TEX\ |<|the inclusion of \EPS\ figures|>| +is replaced by \PDF\ inclusion. \EPS\ files can be converted to \PDF\ by +\GHOSTSCRIPT, Adobe Distiller or other \POSTSCRIPT||to||\PDF\ converters. + +The \PDF\ format is currently the most versatile source format for +graphics embedding. \PDFTEX\ allows to insert arbitrary pages from +\PDF\ files with their own fonts, graphics, and pixel images into +a document. The cover page of this manual is an example of such an insert, +being a one page document generated by \PDFTEX. + +By default \PDFTEX\ takes the BoundingBox of a \PDF\ file from its CropBox +if available, otherwise from its MediaBox. This can be influenced by +the \Something{pdf box spec} option to the \type{\pdfximage} primitive, +or by setting the \type{\pdfpagebox} or \type{\pdfforcepagebox} primitives to +a value corresponding to the wanted box type. + +To get the right BoundingBox from a \EPS\ file, before converting to \PDF, +it is necessary to transform the \EPS\ file so that the start point is +at the (0,0)~coordinate and the page size is set exactly corresponding +to the BoundingBox. A \PERL\ script (\EPSTOPDF) for this purpose has been +written. The \TEXUTIL\ utility script and the \PSTOPDF\ program that comes +with \GHOSTSCRIPT\ can so a similar job. (Concerning this conversion, +they can handle complete directories, remove some garbage from files, +takes precautions against duplicate conversion, etc.) + +The lossless compressing \PNG\ format is great for embedding crisp pixel +graphics (\eg\ line scans, screen shots). Since \PDFTEX\ 1.30.0 also the +alpha-channel of \PNG\ images is processed if available; this allows +embedding of images with simple transparency. The \PNG\ format does not +support the CMYK color model, which is sometimes required for print media +(this often can be replaced by four component \JPEG\ in high quality or +lossless compression mode). Photos in \PNG\ format have a rather weak +compression; here the \JPEG\ format is preferable. + +Embedding \PNG\ images in the general case requires \PDFTEX\ to uncompress +the pixel array and to re||compress it to the \PDF\ requirements; this +process often takes a noticeable amount of time. Since \PDFTEX\ 1.30.0 +there is now a fast \PNG\ embedding mode that goes without uncompressing; +the image data are directly copied into the \PDF\ stream, resulting in +a much higher embedding speed. However this mode is only activated, if +the image array structure of the \PNG\ file is compatible with the \PDF\ +image structure (\eg\ an interlaced \PNG\ image requires uncompressing to +re||arrange the image lines). Luckily it seems that the most common \PNG\ +files also allow fast copying. The use of gamma correction disables fast +copying, as it requires calculations with individual pixels. Whether the +fast copy mode is used for a \PNG\ image can be seen from the log file, +which then shows the string `(PNG copy)' after the \PNG\ file name. + +The \JPEG\ format is normally used in lossy mode; then it's ideal for +embedding photos. It's not recommended for crisp images from synthetic +sources with a limited amount of colors. Both \JFIF\ and \EXIF\ are +supported for additional information. + +The \JBIGTWO\ format works only for bitonal (black and white) pixel +images like scanned line and text documents, but for these it has +typically a much higher compression ratio than the other two pixel +image formats. The \JBIGTWO\ format is part of the \PDF\ standard since +version 1.5; native \JBIGTWO\ image inclusion is available in \PDFTEX\ +since version 1.40.0. A \JBIGTWO\ file might contain many images, which +gives an even better compression ratio than with a single image per file, +as \JBIGTWO\ encoders can exploit similarities between bit patterns over +several images. Encoders for \JBIGTWO\ can operate in lossy as well as +lossless modes. Only recently a free \JBIGTWO\ encoder has been written +and made available, see \from[jbig2enc]. + +Other options for graphics in \PDFTEX\ are: + +\description {\LATEX\ picture mode} Since this is implemented simply in terms +of font characters, it works in exactly the same way as usual. + +\description {Xy||pic} If the \POSTSCRIPT\ back||end is not requested, Xy||pic +uses its own Type~1 fonts, and needs no special attention. + +\description {tpic} The \quote {tpic} \type{\special} commands (used in some +macro packages) can be redefined to produce literal \PDF, using some macros +written by Hans Hagen. + +\description {\METAPOST} Although the output of \METAPOST\ is \POSTSCRIPT, +it is in a highly simplified form, and a \METAPOST\ to \PDF\ conversion +(\MPTOPDF, written by Hans Hagen and Tanmoy Bhattacharya) is implemented +as a set of macros which reads \METAPOST\ output and supports all of +its features. + +For new work, the \METAPOST\ route is highly recommended. For the future, +Adobe has announced that they will define a specification for \quote +{encapsulated \PDF}. + +The inclusion of raw \POSTSCRIPT\ commands |<|a technique utilized +by for instance the \type{pstricks} package|>| cannot directly be +supported. Although \PDF\ is direct a descendant of \POSTSCRIPT, it +lacks any programming language commands, and cannot deal with arbitrary +\POSTSCRIPT. + +%*********************************************************************** + +\section{Character translation} + +Characters that are input to \PDFTEX\ are subject to optional +\TEX\ character translation (\TCX) under control of a \TCX\ file. +The \TCX\ maps the input character codes (\eg\ from \type{\input} or +\type{\read}) to the character codes as seen by \PDFTEX. This mapping +takes place before the characters enter \PDFTEX's `mouth'. If no \TCX\ +file is read, the input characters enter \PDFTEX\ directly; no mapping +is done. + +\TCX\ files consist of lines each containing one or two integer numbers +in the range 0..255, either in decimal or hex notation. +% strtol() C-function +A comment sign \type{%} in a \TCX\ line starts a comment until the +end of line. The first number in each line is for matching the input +character code, the second, optional number is the corresponding \TEX\ +character code. If a line contains only one number, characters with +this code enter \PDFTEX\ unchanged; no mapping is done. + +\TCX\ mapping also influences \PDFTEX\ output streams for \type{\message} and +\type{\write}. Without \TCX\ mapping, only characters that are within +the range 32..126 are flagged as `printable', meaning that these +characters are output directly by \type{\message} and \type{\write} +primitives. Characters outside the range 32..126 are instead output +in escaped form, \eg\ as \type{^^A} for a character with code +\type{0x01}. When a character code is mentioned in the 2nd column of the +\TCX\ file, or as the only value in a line, it is flagged as `printable'. +During \type{\message} and \type{\write}, output characters are mapped +in reverse direction: they are looked up in the 2nd column of the \TCX\ +file and the corresponding values from the 1st column are output. Again, +if a \PDFTEX\ character code is found as the only number in a line, no +mapping is done. Mentioning a character code as the only number on +a line has the sole purpose to flag this code `printable'; remember that +character within the range 32..126 are `printable' anyway. + +The characters output into the \PDF\ file, \eg\ by \type{\pdfliteral} +or \type{\special} primitives, are not subject to \TCX\ output remapping. + +Beware: Character translation interferes with the \ENCTEX\ primitives; to +avoid surprises, don't use \ENCTEX\ and \TCX\ mapping at the same time. +Further details about \TCX\ file loading can be found in the \TETEX\ +manual. + +%*********************************************************************** + +\stopbodymatter + +%D We did use some abbreviations. Only those really used will end up in the +%D following list. + +\startbackmatter + +\writebetweenlist[section]{\blank[line]} + +%*********************************************************************** + +\section{Abbreviations} + +In this document we use numerous abbreviations. For convenience we mention +their meaning here. + +\placelistofabbreviations + +%*********************************************************************** + +\start \setupalign[nothanging,nohz] + +\section{Examples of HZ and protruding} + +In the following sections we will demonstrate \PDFTEX's protruding and +\HZ\ features, using a text from E.~Tufte. This sample text has a lot +of punctuation and often needs hyphenation. Former \PDFTEX\ versions +had sometimes problems with combining these features, but from version +1.21a on it should be ok. If you still encounter problems, please try +to prepare a small test file that demonstrates the problem and send it +to one of the maintainers. + +\startbuffer + \input tufte + \blank[big] + \startcolumns + \input tufte + \stopcolumns +\stopbuffer + +\subsection{Normal} \start \getbuffer \stop +\subsection{HZ} \start \setupalign[hz] \getbuffer \stop +\subsection{Protruding} \start \setupalign[hanging] \getbuffer \stop +\subsection{Both} \start \setupalign[hz,hanging] \getbuffer \stop + +\stop + +%*********************************************************************** + +\section[sec.addpdfkeys]{Additional \PDF\ keys} + +{\em This section is based on the manual on keys written by Martin +Schr\"oder, one of the maintainers of \PDFTEX.} + +A \PDF\ document should contain only the structures and attributes defined +in the \PDF\ specification. However, the specification allows applications +to insert additional keys, provided they follow certain rules. + +The most important rule is that developers have to register with Adobe +prefixes for the keys they want to insert. Hans Hagen has registered the +prefix \type{PTEX} for \PDFTEX. + +\PDFTEX\ generates an XObject for every included \PDF. The dictionary of +this object contains these additional keys: + +\starttabulate[|lT|l|p|] +\HL +\NC \bf key \NC \bf type \NC meaning \NC \NR +\HL +\NC PTEX.FileName \NC string \NC The name of the included file as seen by + \PDFTEX. \NC \NR +\NC PTEX.InfoDict \NC dictionary \NC The document information dictionary of the included + \PDF\ (an indirect object). \NC \NR +\NC PTEX.PageNumber \NC integer \NC The page number of the included file. \NC \NR +\HL +\stoptabulate + +The \PDFReference\ says: \quotation {Although viewer applications can +store custom metadata in the document information dictionary, it is +inappropriate to store private content or structural information there; +such information should be stored in the document catalog instead.} + +Although it would seem more natural to put this information in the +document information dictionary, we have to obey the rules laid down in +the \PDFReference. The following key ends up in the document catalog. + +\starttabulate[|lT|l|p|] +\HL +\NC \bf key \NC \bf type \NC meaning \NC \NR +\HL +\NC PTEX.Fullbanner \NC string \NC The full version of the \pt binary that +produced the file as displayed by {\tt pdftex \hbox{-{}-version}}, \eg\ +{\tt\pdftexbanner}. This is necessary because the string in the +\type{Producer} key in the info dictionary is rather short, +namely {\tt pdfTeX-\currentpdftex}. \NC \NR +\HL +\stoptabulate + +Any or all of these keys can be suppressed with the +\type{\pdfsuppressptexinfo} primitive, described in +\in{section}[sec.docinfocatalog]. + +%*********************************************************************** + +\section{Colophon} + +This manual is typeset in \CONTEXT. One can generate an A4 version from +the source code by typing: + +\starttyping +texexec --result=pdftex-a.pdf pdftex-t +\stoptyping + +Or in letter size: + +\starttyping +texexec --mode=letter --result=pdftex-l.pdf pdftex-t +\stoptyping + +Given that the A4 version is typeset, one can generate an A5 booklet by +typing: + +\starttyping +texexec --pdfarrange --paper=a5a4 --print=up --addempty=1,2 + --result=pdftex-b.pdf pdftex-a +\stoptyping + +Odd and even page sets for non-duplex printers can be generated using +\type{-}\type{-pages=odd} and \type{-}\type{-pages=even} options +(which might require some disciplined shuffling of sheet). + +This also demonstrates that \PDFTEX\ can be used for page imposition +purposes (given that \PDFTEX\ and the fonts are set up properly). + +%*********************************************************************** + +\page + +\definehead[gnusection][subsection] +\definehead[gnusubject][subsubject] + +\setuphead[gnusection,gnusubject][style=\bfa,before=\blank,after=\blank,align={right,broad,nothyphenated}] + +\setuphead[gnusection][ownnumber=yes] + +\section{GNU Free Documentation License} + +\startnotmode[screen] + \switchtobodyfont[4.6pt] % squeeze everything on one page :-} + \setuplayout[grid=yes] + \setupcolumns[n=7] +\stopnotmode + +\startmode[screen] + \setupcolumns[n=2] +\stopmode + +\startcolumns[tolerance=verytolerant,distance=10pt] \widowpenalty10000 \clubpenalty10000 + +\startlines +Version 1.2, November 2002 +Copyright \copyright\ 2000, 2001, 2002 +Free Software Foundation, Inc. +59 Temple Place, Suite 330, +Boston, MA 02111-1307 USA +\stoplines + +Everyone is permitted to copy and distribute verbatim copies +of this license document, but changing it is not allowed. + +\gnusubject{Preamble} + +The purpose of this License is to make a manual, textbook, or other +functional and useful document ``free'' in the sense of freedom: to +assure everyone the effective freedom to copy and redistribute it, +with or without modifying it, either commercially or noncommercially. +Secondarily, this License preserves for the author and publisher a way +to get credit for their work, while not being considered responsible +for modifications made by others. + +This License is a kind of ``copyleft'', which means that derivative +works of the document must themselves be free in the same sense. It +complements the GNU General Public License, which is a copyleft +license designed for free software. + +We have designed this License in order to use it for manuals for free +software, because free software needs free documentation: a free +program should come with manuals providing the same freedoms that the +software does. But this License is not limited to software manuals; +it can be used for any textual work, regardless of subject matter or +whether it is published as a printed book. We recommend this License +principally for works whose purpose is instruction or reference. + +\gnusection{1}{APPLICABILITY AND DEFINITIONS} + +This License applies to any manual or other work, in any medium, that +contains a notice placed by the copyright holder saying it can be +distributed under the terms of this License. Such a notice grants +a world-wide, royalty-free license, unlimited in duration, to use that +work under the conditions stated herein. The {\bf ``Document''}, below, +refers to any such manual or work. Any member of the public is +a licensee, and is addressed as {\bf ``you''}. You accept the license if you +copy, modify or distribute the work in a way requiring permission +under copyright law. + +A {\bf ``Modified Version''} of the Document means any work containing the +Document or a portion of it, either copied verbatim, or with +modifications and/or translated into another language. + +A {\bf ``Secondary Section''} is a named appendix or a front-matter section of +the Document that deals exclusively with the relationship of the +publishers or authors of the Document to the Document's overall subject +(or to related matters) and contains nothing that could fall directly +within that overall subject. (Thus, if the Document is in part +a textbook of mathematics, a Secondary Section may not explain any +mathematics.) The relationship could be a matter of historical +connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding +them. + +The {\bf ``Invariant Sections''} are certain Secondary Sections whose titles +are designated, as being those of Invariant Sections, in the notice +that says that the Document is released under this License. If +a section does not fit the above definition of Secondary then it is not +allowed to be designated as Invariant. The Document may contain zero +Invariant Sections. If the Document does not identify any Invariant +Sections then there are none. + +The {\bf ``Cover Texts''} are certain short passages of text that are listed, +as Front-Cover Texts or Back-Cover Texts, in the notice that says that +the Document is released under this License. A Front-Cover Text may +be at most 5 words, and a Back-Cover Text may be at most 25 words. + +A {\bf ``Transparent''} copy of the Document means a machine-readable copy, +represented in a format whose specification is available to the +general public, that is suitable for revising the document +straightforwardly with generic text editors or (for images composed of +pixels) generic paint programs or (for drawings) some widely available +drawing editor, and that is suitable for input to text formatters or +for automatic translation to a variety of formats suitable for input +to text formatters. A copy made in an otherwise Transparent file +format whose markup, or absence of markup, has been arranged to thwart +or discourage subsequent modification by \PDF\ viewers is not Transparent. +An image format is not Transparent if used for any substantial amount +of text. A copy that is not ``Transparent'' is called {\bf ``Opaque''}. + +Examples of suitable formats for Transparent copies include plain +ASCII without markup, Texinfo input format, LaTeX input format, SGML +or XML using a publicly available DTD, and standard-conforming simple +HTML, \POSTSCRIPT\ or \PDF\ designed for human modification. Examples of +transparent image formats include PNG, XCF and JPG. Opaque formats +include proprietary formats that can be read and edited only by +proprietary word processors, SGML or XML for which the DTD and/or +processing tools are not generally available, and the +machine-generated HTML, \POSTSCRIPT\ or \PDF\ produced by some word +processors for output purposes only. + +The {\bf ''Title Page''} means, for a printed book, the title page itself, +plus such following pages as are needed to hold, legibly, the material +this License requires to appear in the title page. For works in +formats which do not have any title page as such, ``Title Page'' means +the text near the most prominent appearance of the work's title, +preceding the beginning of the body of the text. + +A section {\bf ``Entitled XYZ''} means a named subunit of the Document whose +title either is precisely XYZ or contains XYZ in parentheses following +text that translates XYZ in another language. (Here XYZ stands for +a specific section name mentioned below, such as {\bf ``Acknowledgements''}, +{\bf ``Dedications''}, {\bf ``Endorsements''}, or {\bf ``History''}.) +To {\bf ``Preserve the Title''} +of such a section when you modify the Document means that it remains +a section ``Entitled XYZ'' according to this definition. + +The Document may include Warranty Disclaimers next to the notice which +states that this License applies to the Document. These Warranty +Disclaimers are considered to be included by reference in this +License, but only as regards disclaiming warranties: any other +implication that these Warranty Disclaimers may have is void and has +no effect on the meaning of this License. + + +\gnusection{2}{VERBATIM COPYING} + +You may copy and distribute the Document in any medium, either +commercially or noncommercially, provided that this License, the +copyright notices, and the license notice saying this License applies +to the Document are reproduced in all copies, and that you add no other +conditions whatsoever to those of this License. You may not use +technical measures to obstruct or control the reading or further +copying of the copies you make or distribute. However, you may accept +compensation in exchange for copies. If you distribute a large enough +number of copies you must also follow the conditions in section 3. + +You may also lend copies, under the same conditions stated above, and +you may publicly display copies. + + +\gnusection{3}{COPYING IN QUANTITY} + +If you publish printed copies (or copies in media that commonly have +printed covers) of the Document, numbering more than 100, and the +Document's license notice requires Cover Texts, you must enclose the +copies in covers that carry, clearly and legibly, all these Cover +Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on +the back cover. Both covers must also clearly and legibly identify +you as the publisher of these copies. The front cover must present +the full title with all words of the title equally prominent and +visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve +the title of the Document and satisfy these conditions, can be treated +as verbatim copying in other respects. + +If the required texts for either cover are too voluminous to fit +legibly, you should put the first ones listed (as many as fit +reasonably) on the actual cover, and continue the rest onto adjacent +pages. + +If you publish or distribute Opaque copies of the Document numbering +more than 100, you must either include a machine-readable Transparent +copy along with each Opaque copy, or state in or with each Opaque copy +a computer-network location from which the general network-using +public has access to download using public-standard network protocols +a complete Transparent copy of the Document, free of added material. +If you use the latter option, you must take reasonably prudent steps, +when you begin distribution of Opaque copies in quantity, to ensure +that this Transparent copy will remain thus accessible at the stated +location until at least one year after the last time you distribute an +Opaque copy (directly or through your agents or retailers) of that +edition to the public. + +It is requested, but not required, that you contact the authors of the +Document well before redistributing any large number of copies, to give +them a chance to provide you with an updated version of the Document. + + +\gnusection{4}{MODIFICATIONS} + +You may copy and distribute a Modified Version of the Document under +the conditions of sections 2 and 3 above, provided that you release +the Modified Version under precisely this License, with the Modified +Version filling the role of the Document, thus licensing distribution +and modification of the Modified Version to whoever possesses a copy +of it. In addition, you must do these things in the Modified Version: + +\startitemize[A,packed] +\item + Use in the Title Page (and on the covers, if any) a title distinct + from that of the Document, and from those of previous versions + (which should, if there were any, be listed in the History section + of the Document). You may use the same title as a previous version + if the original publisher of that version gives permission. + +\item + List on the Title Page, as authors, one or more persons or entities + responsible for authorship of the modifications in the Modified + Version, together with at least five of the principal authors of the + Document (all of its principal authors, if it has fewer than five), + unless they release you from this requirement. + +\item + State on the Title page the name of the publisher of the + Modified Version, as the publisher. + +\item + Preserve all the copyright notices of the Document. + +\item + Add an appropriate copyright notice for your modifications + adjacent to the other copyright notices. + +\item + Include, immediately after the copyright notices, a license notice + giving the public permission to use the Modified Version under the + terms of this License, in the form shown in the Addendum below. + +\item + Preserve in that license notice the full lists of Invariant Sections + and required Cover Texts given in the Document's license notice. + +\item + Include an unaltered copy of this License. + +\item + Preserve the section Entitled ``History'', Preserve its Title, and add + to it an item stating at least the title, year, new authors, and + publisher of the Modified Version as given on the Title Page. If + there is no section Entitled ``History'' in the Document, create one + stating the title, year, authors, and publisher of the Document as + given on its Title Page, then add an item describing the Modified + Version as stated in the previous sentence. + +\item + Preserve the network location, if any, given in the Document for + public access to a Transparent copy of the Document, and likewise + the network locations given in the Document for previous versions + it was based on. These may be placed in the ``History'' section. + You may omit a network location for a work that was published at + least four years before the Document itself, or if the original + publisher of the version it refers to gives permission. + +\item + For any section Entitled ``Acknowledgements'' or ``Dedications'', + Preserve the Title of the section, and preserve in the section all + the substance and tone of each of the contributor acknowledgements + and/or dedications given therein. + +\item + Preserve all the Invariant Sections of the Document, + unaltered in their text and in their titles. Section numbers + or the equivalent are not considered part of the section titles. + +\item + Delete any section Entitled ``Endorsements''. Such a section + may not be included in the Modified Version. + +\item + Do not retitle any existing section to be Entitled ``Endorsements'' + or to conflict in title with any Invariant Section. + +\item + Preserve any Warranty Disclaimers. +\stopitemize + +If the Modified Version includes new front-matter sections or +appendices that qualify as Secondary Sections and contain no material +copied from the Document, you may at your option designate some or all +of these sections as invariant. To do this, add their titles to the +list of Invariant Sections in the Modified Version's license notice. +These titles must be distinct from any other section titles. + +You may add a section Entitled ``Endorsements'', provided it contains +nothing but endorsements of your Modified Version by various +parties---for example, statements of peer review or that the text has +been approved by an organization as the authoritative definition of +a standard. + +You may add a passage of up to five words as a Front-Cover Text, and +a passage of up to 25 words as a Back-Cover Text, to the end of the list +of Cover Texts in the Modified Version. Only one passage of +Front-Cover Text and one of Back-Cover Text may be added by (or +through arrangements made by) any one entity. If the Document already +includes a cover text for the same cover, previously added by you or +by arrangement made by the same entity you are acting on behalf of, +you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. + +The author(s) and publisher(s) of the Document do not by this License +give permission to use their names for publicity for or to assert or +imply endorsement of any Modified Version. + +\gnusection{5}{COMBINING DOCUMENTS} + +You may combine the Document with other documents released under this +License, under the terms defined in section 4 above for modified +versions, provided that you include in the combination all of the +Invariant Sections of all of the original documents, unmodified, and +list them all as Invariant Sections of your combined work in its +license notice, and that you preserve all their Warranty Disclaimers. + +The combined work need only contain one copy of this License, and +multiple identical Invariant Sections may be replaced with a single +copy. If there are multiple Invariant Sections with the same name but +different contents, make the title of each such section unique by +adding at the end of it, in parentheses, the name of the original +author or publisher of that section if known, or else a unique number. +Make the same adjustment to the section titles in the list of +Invariant Sections in the license notice of the combined work. + +In the combination, you must combine any sections Entitled ``History'' +in the various original documents, forming one section Entitled +``History''; likewise combine any sections Entitled ``Acknowledgements'', +and any sections Entitled ``Dedications''. You must delete all sections +Entitled ``Endorsements''. + +\gnusection{6}{COLLECTIONS OF DOCUMENTS} + +You may make a collection consisting of the Document and other documents +released under this License, and replace the individual copies of this +License in the various documents with a single copy that is included in +the collection, provided that you follow the rules of this License for +verbatim copying of each of the documents in all other respects. + +You may extract a single document from such a collection, and distribute +it individually under this License, provided you insert a copy of this +License into the extracted document, and follow this License in all +other respects regarding verbatim copying of that document. + +\gnusection{7}{AGGREGATION WITH INDEPENDENT WORKS} + +A compilation of the Document or its derivatives with other separate +and independent documents or works, in or on a volume of a storage or +distribution medium, is called an ``aggregate'' if the copyright +resulting from the compilation is not used to limit the legal rights +of the compilation's users beyond what the individual works permit. +When the Document is included in an aggregate, this License does not +apply to the other works in the aggregate which are not themselves +derivative works of the Document. + +If the Cover Text requirement of section 3 is applicable to these +copies of the Document, then if the Document is less than one half of +the entire aggregate, the Document's Cover Texts may be placed on +covers that bracket the Document within the aggregate, or the +electronic equivalent of covers if the Document is in electronic form. +Otherwise they must appear on printed covers that bracket the whole +aggregate. + +\gnusection{8}{TRANSLATION} + +Translation is considered a kind of modification, so you may +distribute translations of the Document under the terms of section 4. +Replacing Invariant Sections with translations requires special +permission from their copyright holders, but you may include +translations of some or all Invariant Sections in addition to the +original versions of these Invariant Sections. You may include +a translation of this License, and all the license notices in the +Document, and any Warranty Disclaimers, provided that you also include +the original English version of this License and the original versions +of those notices and disclaimers. In case of a disagreement between +the translation and the original version of this License or a notice +or disclaimer, the original version will prevail. + +If a section in the Document is Entitled ``Acknowledgements'', +``Dedications'', or ``History'', the requirement (section 4) to Preserve +its Title (section~1) will typically require changing the actual +title. + +\gnusection{9}{TERMINATION} + +You may not copy, modify, sublicense, or distribute the Document except +as expressly provided for under this License. Any other attempt to +copy, modify, sublicense or distribute the Document is void, and will +automatically terminate your rights under this License. However, +parties who have received copies, or rights, from you under this +License will not have their licenses terminated so long as such +parties remain in full compliance. + +\gnusection{10}{FUTURE REVISIONS OF THIS LICENSE} + +The Free Software Foundation may publish new, revised versions +of the GNU Free Documentation License from time to time. Such new +versions will be similar in spirit to the present version, but may +differ in detail to address new problems or concerns. See +http:/\!/www.gnu.org/copyleft/. + +Each version of the License is given a distinguishing version number. +If the Document specifies that a particular numbered version of this +License ``or any later version'' applies to it, you have the option of +following the terms and conditions either of that specified version or +of any later version that has been published (not as a draft) by the +Free Software Foundation. If the Document does not specify a version +number of this License, you may choose any version ever published (not +as a draft) by the Free Software Foundation. +\stopcolumns + +%*********************************************************************** + +\stopbackmatter + +%D And then we're done. + +% Evidently ConTeXt somewhere sets \pdfgentounicode=1. Or something. +% So insert the mappings. Seems like a good thing anyway. +\input glyphtounicode +\stoptext |