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