From f00674867edd34b9391b6db2a8442ccb581138c9 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Tue, 1 Mar 2022 02:09:14 +0000 Subject: pdftex manual update for 1.40.24 (TeX Live 2022) git-svn-id: svn://tug.org/texlive/trunk@62306 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/doc/pdftex/manual/ChangeLog | 43 + Master/texmf-dist/doc/pdftex/manual/Makefile | 7 +- Master/texmf-dist/doc/pdftex/manual/pdftex-a.pdf | Bin 948745 -> 1002639 bytes .../texmf-dist/doc/pdftex/manual/pdftex-syntax.txt | 23 +- Master/texmf-dist/doc/pdftex/manual/pdftex-t.tex | 6681 ++++++++++---------- 5 files changed, 3511 insertions(+), 3243 deletions(-) diff --git a/Master/texmf-dist/doc/pdftex/manual/ChangeLog b/Master/texmf-dist/doc/pdftex/manual/ChangeLog index 8d85229fc3b..70cf61a9301 100644 --- a/Master/texmf-dist/doc/pdftex/manual/ChangeLog +++ b/Master/texmf-dist/doc/pdftex/manual/ChangeLog @@ -1,3 +1,46 @@ +2022-02-28 Karl Berry + + * pdftex-t.tex (ptex_devel): svn://tug.org url. + +2021-11-06 Marcel Kr\"uger + + * pdftex-t.tex (\showstream): document. + +2021-11-06 Marcel Kr\"uger + + * pdftex-t.tex: missed bookmarks for \pdfgentounicode and + a few other primitives. + +2021-11-04 Karl Berry + + * pdftex-t.tex: size GFDL for two pages, since it was spilling over. + Let first bodyfont size stand. + Rearrange some text for new font size. + +2021-11-04 Marcel Kr\"uger + + * pdftex-t.tex: document structured destinations (\pdfdest struct NNN). + Also bump document font size to 11pt. + +2021-09-25 Karl Berry + + * pdftex-t.tex (\pdfstartlink): organize into lists. + +2021-07-25 Karl Berry + + * pdftex-t.tex: oops, \partokencontext sorts before \partokenname. + * pdftex-t.tex (\partokenname, \partokencontext): document these + new primitives. + +2021-07-24 Karl Berry + + * pdftex-t.tex (Installation): rename this section from "Getting + started", and move to the end. + (Macro programming, Typesetting, Tracing, \PDFTEX\ execution + environment): split "Miscellanous" primitives subsection into these. + (Character translation): move to before Abbreviations. + No substantive changes to the content in any of this. + 2021-02-18 Karl Berry * pdftex-t.tex: update for 2021: diff --git a/Master/texmf-dist/doc/pdftex/manual/Makefile b/Master/texmf-dist/doc/pdftex/manual/Makefile index 05c57fc29a5..adbb1c7c95a 100644 --- a/Master/texmf-dist/doc/pdftex/manual/Makefile +++ b/Master/texmf-dist/doc/pdftex/manual/Makefile @@ -1,4 +1,4 @@ -# $Id: Makefile 848 2021-02-18 17:49:17Z karl $ +# $Id: Makefile 875 2022-03-01 02:08:10Z karl $ # Makefile for pdfTeX documentation. Public domain. # Get version we're documenting from the \def in the manual. @@ -88,7 +88,7 @@ pdftex-syntax.txt: pdftex-t.tex pdftex-syntax.tex syntaxform.awk # Install from this source directory to TL. # svn co svn://u:pw@tug.org/texlive/trunk/Master/texmf-dist/doc/pdftex -tltree = /r/tug/home/texlive/karl/Master/texmf-dist +tltree = /v/texlive/karl/Master/texmf-dist dest = $(tltree)/doc/pdftex/manual INSTALL_DATA = cp -p @@ -145,3 +145,6 @@ maintainer-clean: clean rm -f pdftex-w.pdf pdftex-w.txt clobber allclean realclean distclean: maintainer-clean + +spell: + myspell pdftex-t.tex diff --git a/Master/texmf-dist/doc/pdftex/manual/pdftex-a.pdf b/Master/texmf-dist/doc/pdftex/manual/pdftex-a.pdf index f5d6372f936..4fa8985b52d 100644 Binary files a/Master/texmf-dist/doc/pdftex/manual/pdftex-a.pdf and b/Master/texmf-dist/doc/pdftex/manual/pdftex-a.pdf differ diff --git a/Master/texmf-dist/doc/pdftex/manual/pdftex-syntax.txt b/Master/texmf-dist/doc/pdftex/manual/pdftex-syntax.txt index 7125d653fd0..31b92f29e9e 100644 --- a/Master/texmf-dist/doc/pdftex/manual/pdftex-syntax.txt +++ b/Master/texmf-dist/doc/pdftex/manual/pdftex-syntax.txt @@ -44,6 +44,7 @@ \pdfuniqueresname (integer) \rpcode <8-bit number> (integer) \shbscode <8-bit number> (integer) +\showstream (integer) \stbscode <8-bit number> (integer) \tagcode <8-bit number> (integer) \tracinglostchars (integer) @@ -123,6 +124,7 @@ %% General commands: \letterspacefont +\partokenname \pdfannot (h, v, m) \pdfcatalog [openaction ] \pdfcolorstack @@ -188,11 +190,12 @@ | goto | thread --> - --> - | [] - | [] [] - | - | [] + --> struct ( | nameid | ) + --> [] + | [] [] + | [] [] [] + | [] + | [] [] --> [] | [] --> colorspace @@ -202,8 +205,9 @@ --> num --> name --> newwindow | nonewwindow - --> - | + --> [struct ] \\ + ( | ) + --> xyz [zoom ] | fitr | fitbh @@ -226,3 +230,8 @@ --> pdf: | PDF: --> direct: --> set | push | pop | current + --> [] + | [] [] + | [] [] [] + | [] + | [] [] diff --git a/Master/texmf-dist/doc/pdftex/manual/pdftex-t.tex b/Master/texmf-dist/doc/pdftex/manual/pdftex-t.tex index 2f323fedce3..02af91417f2 100644 --- a/Master/texmf-dist/doc/pdftex/manual/pdftex-t.tex +++ b/Master/texmf-dist/doc/pdftex/manual/pdftex-t.tex @@ -1,7 +1,7 @@ % interface=english modes=letter,screen output=pdftex % vim: tw=79 -% $Id: pdftex-t.tex 849 2021-02-18 17:55:44Z karl $ +% $Id: pdftex-t.tex 875 2022-03-01 02:08:10Z karl $ % The number of lines on the title page depends on exactly % what \PDF\ code is generated. @@ -38,7 +38,7 @@ August\or September\or October\or November\or December\else ERROR\fi} } -\svnscan $Id: pdftex-t.tex 849 2021-02-18 17:55:44Z karl $ +\svnscan $Id: pdftex-t.tex 875 2022-03-01 02:08:10Z karl $ \def\currentpdftex{1.40.22} @@ -73,17 +73,17 @@ \abbreviation [JPEG] {jpeg} {Joint Photographic Experts Group} \abbreviation [LATEX] {\LaTeX} {general purpose macro package} \abbreviation [MAC] {Macintosh} {Macintosh hardware platform} -\abbreviation [MACOSX] {Mac\,OS\,X} {Macintosh operating system version 10} -\abbreviation [MACTEX] {Mac\TeX} {\MAC\ \WEBC\ distribution} +\abbreviation [MACOSX] {Mac\,OS\,X} {Macintosh operating system version 10+} +\abbreviation [MACTEX] {Mac\TeX} {\MAC\ \TEXLIVE\ distribution} \abbreviation [METAFONT] {\MetaFont} {graphic programming environment, bitmap output} \abbreviation [METAPOST] {\MetaPost} {graphic programming environment, vector output} \abbreviation [MIKTEX] {MiK\TeX} {\WIN\ distribution} \abbreviation [MLTEX] {ml\TeX} {ML\TeX\ extension to \TEX} \abbreviation [MPTOPDF] {mptopdf} {\METAPOST\ to \PDF\ conversion tool} \abbreviation [MSDOS] {ms-dos} {Microsoft DOS platform (Intel)} -\abbreviation [PDFETEX] {pdfe\TeX} {\ETEX\ extension producing \PDF\ output} -\abbreviation [PDFLATEX] {pdf\LaTeX} {\TEX\ extension producing \PDF\ output (\LATEX\ format loaded)} -\abbreviation [PDFTEX] {pdf\TeX} {\TEX\ extension producing \PDF\ output} +\abbreviation [PDFETEX] {pdfe\TeX} {\ETEX\ extension supporting \PDF\ output} +\abbreviation [PDFLATEX] {pdf\LaTeX} {\LATEX\ format using \PDFTEX, producing \PDF} +\abbreviation [PDFTEX] {pdf\TeX} {\TEX\ extension supporting \PDF\ output} \abbreviation [PDF] {pdf} {Portable Document Format} \abbreviation [PDFA] {pdf/\kern-.16em a} {PDF A/ standards} \abbreviation [PERL] {Perl} {Perl programming environment} @@ -100,19 +100,18 @@ \abbreviation [TCX] {tcx} {\TEX\ Character Translation} \abbreviation [TDS] {tds} {\TEX\ Directory Standard} \abbreviation [TEXEXEC] {\TeX exec} {\CONTEXT\ command line interface} -\abbreviation [TEXINFO] {Texinfo} {generate typeset documentation from info pages} +\abbreviation [TEXINFO] {Texinfo} {\GNU\ documentation format} \abbreviation [TEXUTIL] {\TeX util} {\CONTEXT\ utility tool} \abbreviation [TEX] {\TeX} {typographic language and program} -\abbreviation [TEXLIVE] {\TeX\ Live} {\TeX\ Live distribution (multiple platform)} +\abbreviation [TEXLIVE] {\TeX\ Live} {\TeX\ Live distribution (cross-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 [WEBC] {Web2c} {Implementation framework for \TEX\ and friends} \abbreviation [WEB] {web} {literate programming environment} \abbreviation [WIN] {Windows} {Microsoft Windows platform} -\abbreviation [ZIP] {zip} {compressed file format} %D It makes sense to predefine the name of the author of \PDFTEX, doesn't it? @@ -123,7 +122,7 @@ \useURL [ptex_org] [http://www.pdftex.org] % links to ptex_examples \useURL [ptex_ctan] [https://ctan.org/pkg/pdftex] -\useURL [ptex_devel] [http://foundry.supelec.fr/projects/pdftex] +\useURL [ptex_devel] [svn://tug.org/pdftex/branches/stable] % where bug reports should go: \useURL [ptex_bugs] [mailto:pdftex@tug.org] [] [pdftex@tug.org] @@ -142,9 +141,6 @@ \useURL [thanh_truetype_tub] [https://tug.org/TUGboat/tb30-1/tb94thanh.pdf] \useURL [jbig2enc] [https://github.com/agl/jbig2enc] -%D The primitive definitions are specified a bit fuzzy using the next set of -%D commands. Some day I'll write some proper macros to deal with this. - % keep next 2 lines as temporary kludge for a while to make \type{} of % older ConTeXt versions handle these two new primitives; the original % problem with \type{} is already solved in ConTeXt as of 2006-02-14. @@ -153,7 +149,8 @@ \def\Syntax #1{\strut\kern-.25em{#1}\kern-.25em\relax} \def\Next {\crlf\hbox to 2em{}\nobreak} -\def\Sugar #1{\unskip\unskip\unskip\kern.25em{#1}\kern.25em\ignorespaces} +\def\Sugar #1{\unskip\unskip\unskip\kern.25em{#1}\kern.25em + \penalty0 \ignorespaces} % allow break % \def\Lbrace {\Sugar{\tttf\leftargument}} \def\Literal #1{\Sugar{\type{#1}}} @@ -337,8 +334,6 @@ \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! @@ -347,7 +342,7 @@ \usetypescript [palatino][\defaultencoding] \setupbodyfont - [palatino,10pt] + [palatino,11pt] \definefontsynonym[TitleFont][SerifBold] @@ -364,8 +359,6 @@ \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] @@ -692,7 +685,7 @@ Please send questions or suggestions by email to \from[ptex_bugs]. \subsection{Legal Notice} -Copyright \copyright\ 1996||2020 \THANH. +Copyright \copyright\ 1996||2022 \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; @@ -830,4017 +823,4295 @@ We now turn to specifics of \PDFTEX. %*********************************************************************** -\section{Getting started} +\section{Invoking \PDFTEX} -This section describes the steps needed to get \PDFTEX\ running on -a system where \PDFTEX\ is not yet installed. Nowadays virtually all -\TEX\ distributions have \PDFTEX\ as a component, such as \TEXLIVE, -\MIKTEX, \PROTEXT, and \MACTEX. The ready to run -\TEXLIVE\ distribution comes with \PDFTEX\ versions for many \UNIX, -\WIN, and \MACOSX\ systems; more information can be found at -\hbox{\from[texlive].} There are also \WIN-specific distributions which -contain \PDFTEX, under \from[win32]: \MIKTEX\ by Christian Schenk, and -\PROTEXT\ (based on \MIKTEX) by Thomas Feuerstack. When you use any -of these distributions, you don't need to bother with the \PDFTEX\ -installation procedure in the next sections. +\PDFTEX\ has many command line options. Except for the simple and +rarely-used \type{-draftmode} and \type{-output-format} options, they +are all inherited from the common framework for \TeX\ engines as +implemented in \WEBC\ (its manual is available at \from [web2c]). -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, into which the freshly compiled \PDFTEX\ will -be integrated. Note that the installation description in this manual -is \WEBC||specific. +The same commonality holds for environment variables; see the section +``Setting search paths'' above for an overview. Two additional +environment variables need more description here: first, +\type{SOURCE_DATE_EPOCH} (introduced in version 1.40.17, 2016). If this +is set, it must be a positive integer (with one trivial exception: if it +is set but empty, that is equivalent to 0). Non-integer values cause a +fatal error. The value is used as the current time in seconds since the +usual Unix ``epoch'': the beginning of 1970-01-01, UTC. Thus, a value +of \type{32} would result in a \type{/CreationDate} and \type{/ModDate} +values of \type{19700101000032Z}. This is useful for reproducible +builds of documents. (See also \type{\pdfinfoomitdate}, +\type{\pdfsuppressptexinfo}, et al.) -%*********************************************************************** +The second, related, environment variable is \type{FORCE_SOURCE_DATE}. +If this is set to~\type{1}, \TEX's time-related primitives are also +initialized from the value of \type{SOURCE_DATE_EPOCH}. These primitives +are \type{\year}, \type{\month}, \type{\day}, and \type{\time}. If +\type{SOURCE_DATE_EPOCH} is not set, setting \type{FORCE_SOURCE_DATE} +has no effect. If \type{FORCE_SOURCE_DATE} is unset, set to the empty +string, or set to~\type{0}, the primitives reflect the current time as +usual. Any other value elicits a warning, and the current time is used. +This is useful if one wants to make reproducible \PDF{}s for a set +of documents without changing them in any way, e.g., an operating system +distribution with manuals that use \type{\today}. Except in such unusual +circumstances, it is better not to set this, and let the \TEX\ +primitives retain the meaning they have always had. -\subsection{Getting sources and binaries} +In addition, if both \type{SOURCE_DATE_EPOCH} and +\type{FORCE_SOURCE_DATE} are set, \type{\pdffilemoddate} returns a value +in UTC, ending in \type{Z}. (The values of the environment variables are +irrelevant in this case.) -The latest sources of \PDFTEX\ are distributed for compilation on \UNIX\ -systems (including \GNU/Linux), and \WIN\ systems. The primary home -page is \from[ptex_org], where you also find bug tracking information. -Development sources are at \from[ptex_devel]. Precompiled \PDFTEX\ -binaries for various systems might be available in subdirectories below -\from[ctan_systems], or via \TEX\ distribution web pages. +Finally, just to have the list of options and basic invocation at hand, +here is a verbatim listing of the \type{-}\type{-help} output. All +options can be specified with one or two dashes and unambiguously +abbreviated. -%*********************************************************************** +\begingroup +\startnotmode[screen] + \switchtobodyfont[10pt] % keep line lengths shorter +\stopnotmode -\subsection{Compiling} +\typefile{pdftex-help.txt} -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: +\endgroup -\startesctyping -cd pdftex.../source -./build-pdftex.sh -\stopesctyping +%*********************************************************************** -The binary \filename{pdftex} is then built in the subdirectory -\filename{build/texk/web2c}. +\section{Macro packages supporting \PDFTEX} -The obsolescent binary \filename{pdfetex} is still generated for backward -compatibility, but since version 1.40 it is just a symbolic link to or copy -of the file \filename{pdftex}. +As \PDFTEX\ generates the final \PDF\ output without help of +a postprocessor, macro packages that take care of these \PDF\ features +have to be set up properly. Typical tasks are handling color, +graphics, hyperlink support, threading, font||inclusion, as well as +page imposition and manipulation. All these \PDF||specific tasks can be +controlled by \PDFTEX's own primitives (a few also by a \PDFTEX||specific +\type{\special{pdf: ...}} primitive). Any other \type{\special{}} commands, +like the ones defined for various \DVI\ postprocessors, are simply +ignored by \PDFTEX\ when in \PDF\ output mode; a warning is given only +for non||empty \type{\special{}} commands. -As well as the main \filename{pdftex} binary, binaries for the utilities -\filename{pdftosrc} and \filename{ttf2afm} are generated. +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 -Incidentally, for \PDFTEX\ maintains, a sibling script to -\type{build-pdftex.sh} is included, namely \type{sync-pdftex.sh}, which -syncs changes from a \TEXLIVE\ source repository to a \PDFTEX\ source -repository. Read the script before using it. And don't use it unless -you understand what you read. +\starttyping +\pdfoutput=1 \let\special\message +\stoptyping -%*********************************************************************** +or, if this leads to confusion, -\subsection{Placing files} +\starttyping +\pdfoutput=1 \def\special#1{\write16{special: #1}} +\stoptyping -The next step is to put the freshly compiled \filename{pdftex}, -\filename{pdftosrc}, and \filename{ttf2afm} binaries into the binary -directory (\eg\ for a typical \TEXLIVE\ system, and on the appropriate -platform) \filename{/usr/local/texlive/\rcsyear/bin/x86_64-linux}. +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. -If you're doing this into a live hierarchy, don't forget to do a -\type{texconfig-sys init} afterwards, so that all formats are -regenerated system-wide with the fresh \filename{pdftex} binary. +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 -\subsection{Setting search paths} +\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. -\WEBC||based programs, including \PDFTEX, use the \WEBC\ run||time -configuration file called \filename {texmf.cnf}. The location -of this file is the appropriate position within the \TDS\ tree -relative to the place of the \PDFTEX\ binary; on a \TEXLIVE\ system, -\filename{texmf.cnf} is typically located either in the directory -\filename{texmf-dist/web2c}. The path to -file \filename{texmf.cnf} can also be set up by the environment variable -\type{TEXMFCNF}. +\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. -The configuration files in the major \TEX\ distributions (such as -\filename{texmf.cnf} in \TEXLIVE) should already be set up for normal -use, so you shouldn't need to edit it. You might still like to read it -to see where the various bits and pieces are going. +\item The \CONTEXT\ macro package by Hans Hagen has very full support + for \PDFTEX\ in its generalized hypertext features. Support for + \PDFTEX\ is implemented as a special driver, and is invoked by + typing \type{\setupoutput[pdftex]} or feeding \TEXEXEC\ with the + \hbox{\tt -{}-pdf} option. -\PDFTEX\ uses the search path variables shown in -\in{table}[tbl:spathvar], among others. +\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}. -\startbuffer -\starttabulate[|l|l|] -\HL -\NC \bf used for \NC \bf texmf.cnf \NC\NR -\HL -\NC output files \NC \type{TEXMFOUTPUT} \NC\NR -\NC input files, images \NC \type{TEXINPUTS} \NC\NR -\NC format files \NC \type{TEXFORMATS} \NC\NR -\NC \TeX\ pool files \NC \type{TEXPOOL} \NC\NR -\NC encoding files \NC \type{ENCFONTS} \NC\NR -\NC font map files \NC \type{TEXFONTMAPS} \NC\NR -\NC \TFM\ files \NC \type{TFMFONTS} \NC\NR -\NC virtual fonts \NC \type{VFFONTS} \NC\NR -\NC Type~1 fonts \NC \type{T1FONTS} \NC\NR -\NC TrueType fonts \NC \type{TTFONTS} \NC\NR -\NC OpenType fonts \NC \type{OPENTYPEFONTS} \NC\NR -\NC bitmap fonts \NC \type{PKFONTS} \NC\NR -\HL -\stoptabulate -\stopbuffer +\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. -\placetable[here][tbl:spathvar] - {The principal \WEBC\ variables.} - {\getbuffer} +\stopitemize -\PathDescription {TEXMFOUTPUT} Normally, \PDFTEX\ puts its output files -in the current directory, overridden by the \type{-output-directory} -option. If any output file cannot be opened there, it tries to open it -in the environment variable \type{TEXMFOUTPUT}, if that is set. There is -no default value for that variable. For example, if \type{TEXMFOUTPUT} -has the value \type{/tmp}, and you run \type{pdftex paper} when the -current directory is not writable, \PDFTEX\ attempts to create -\type{/tmp/paper.log} (and \type{/tmp/paper.pdf}, etc.) +Some nice samples of \PDFTEX\ output can be found at +\from[ptex_org], \from[context], and \from[tex_showcase]. -\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. +\section{Setting up fonts} -\PathDescription {TEXPOOL} Search path for pool (\type{.pool}) files; no -longer used, since the pool file (program strings) are compiled into -the binary. +\PDFTEX\ can work with Type~1 and TrueType fonts (and to some extent +also with OpenType fonts). Font files should be available and embedded +for all fonts used in the generated PDF. It is possible to use +\METAFONT||generated fonts in \PDFTEX\ --- but it is strongly +recommended not to use these fonts if an equivalent is available in +Type~1 or TrueType format, if only because bitmap Type~3 fonts render +poorly under enlargement. -\PathDescription {ENCFONTS} Search path for encoding (\type{.enc}) files. +%*********************************************************************** -\PathDescription {TEXFONTMAPS} Search path for font map (\type{.map}) files. +\subsection[mapfile]{Map files} -\PathDescription {TFMFONTS} Search path for font metric (\type{.tfm}) files. +Font map files provide the connection between \TEX\ \TFM\ font files +and outline font file names. They contain also information about +re||encoding arrays, partial font embedding (``subsetting''), and +character transformation parameters (like SlantFont and ExtendFont). Those +map files were first created for \DVI\ postprocessors. But, as \PDFTEX\ +in \PDF\ output mode includes all \PDF\ processing steps, it also needs +to know about font mapping, and therefore reads in one or more map files. +Map files are not read in when \PDFTEX\ is in \DVI\ mode. Bitmap fonts +can (and normally should) be used without being listed in the map file. -\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. +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. -\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. +Within the map file, each font is listed on a single line. The syntax of +each line is upward||compatible with \type{dvips} map files and can contain +the following fields (some are optional; explanations follow): -\PathDescription {TTFONTS,\hfil\break \hbox{OPENTYPEFONTS}} Search paths -for TrueType (\type{.ttf}) and OpenType (\type{.otf}) font files. Like -Type~1 fonts, TrueType and OpenType fonts are also outlines. +\startnarrower +{\em tfmname psname fontflags special encodingfile fontfile} +\stopnarrower -\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). +It is mandatory that {\em tfmname} is the first field. If a {\em +psname} is given, it must be the second field. Similarly if {\em +fontflags} is given it must be the third field (if {\em psname} is +present) or the second field (if {\em psname} is left out). The +positions of {\em special}, {\em encodingfile}, and {\em fontfile} can +be mixed. -\PathDescription{TEXFONTS} Fallback for all the font paths, so that if -you want to look in a particular directory for fonts on a given run, you -can set that one variable. +\startdescription {tfmname} +sets the name of the \TFM\ file for a font --- the file name given in a +\TEX\ \type{\font} command. This name must always be given. -Many more variables may be consulted, and there are many details to -file name lookups. See the Kpathsea manual (\from [kpathsea]). +\stopdescription -%*********************************************************************** +\startdescription {psname} +sets the (\POSTSCRIPT) base font name, which has two uses: -\subsection[cfg]{The \PDFTEX\ configuration} +First, when a \PDF\ file is embedded by \type{\pdfximage}, the +\type{/BaseFont} names in the font dictionaries of Type~1 and Type~1C +(CFF) fonts from the embedded \PDF\ file are checked against this {\em +psname} field. If names match, the glyphs of that font will not be +copied from the embedded \PDF\ file, but instead a local font is opened, +and all needed glyphs will be taken from the Type~1 font file that is +mentioned in the map line (see {\em fontfile} below). By this collecting +mechanism Type~1 glyphs can be shared between several embedded \PDF\ +files and with text that is typeset by \PDFTEX, which helps keeping the +resulting \PDF\ file size small, if many files with similar Type~1(C) +fonts are embedded. Replacing Type~1 fonts from embedded \PDF\ files +requires that also a Type~1 font file name is in the {\em fontfile} field +(see below). -We must keep in mind that, as opposed to \TEX\ with its \DVI\ output, -the \PDFTEX\ program does not have a separate postprocessing stage to -transform the \TEX\ input into final \PDF. As a consequence, all data -needed for building a ready \PDF\ page must be available during the -\PDFTEX\ run, in particular information on media dimensions and offsets, -graphics files for embedding, and font information (font files, -encodings). +Second, if a font file is not to be embedded into the \PDF\ output +({\em fontfile} field missing), then the {\em psname} field will be +copied to the \type{/BaseFont} and \type{/FontName} dictionary entries +in the \PDF\ file, so that the \POSTSCRIPT\ font name will be known to +reading applications (\eg\ viewers). -When \TEX\ builds a page, it places items relative to the (1in,1in) -offset from 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. +It is highly recommended to use the {\em psname} field, but +strictly speaking it is optional. -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. +\stopdescription -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. +\startdescription {fontflags} +optionally specify some characteristics of the font. The following description of +these flags is taken, with slight modification, from the \PDFReference\ +(the section on font descriptor flags). Viewers can adapt their rendering +to these flags, especially when they substitute a non-embedded font by +some own approximation. -A list of \PDFTEX\ primitives relevant to setting up the \PDFTEX\ engine -is given in \in{table}[tbl:configparms]. All primitives are described in -detail within later sections. \in{Figure}[in:pdftexconfig] shows a recent -configuration file (\type{pdftexconfig.tex}) in \TEX\ format, using the -primitives from \in{table}[tbl:configparms], which typically is read -in during the format building process. It enables \PDF\ output, sets paper -dimensions and the default pixel density for \PK\ font inclusion. The default -values are chosen so that \PDFTEX\ often can be used (\eg\ in \type{-ini} mode) -even without setting any parameters. +\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[|l|l|l|l|l|] +\starttabulate[|c|l|] \HL -\NC \bf internal name \NC \bf type \NC\bf default\NC\bf comment\NC\NR +\NC \bf bit position \NC \bf semantics \NC\NR \HL -\NC \type{\pdfoutput} \NC integer \NC 0 \NC \DVI \NC\NR -\NC \type{\pdfadjustspacing} \NC integer \NC 0 \NC off \NC\NR -\NC \type{\pdfcompresslevel} \NC integer \NC 9 \NC best \NC\NR -\NC \type{\pdfobjcompresslevel} \NC integer \NC 0 \NC no object streams \NC\NR -\NC \type{\pdfdecimaldigits} \NC integer \NC 4 \NC max. \NC\NR -\NC \type{\pdfimageresolution} \NC integer \NC 72 \NC dpi \NC\NR -\NC \type{\pdfpkresolution} \NC integer \NC 0 \NC 72\,dpi \NC\NR -\NC \type{\pdfpkmode} \NC token reg.\NC empty \NC mode set in \type{mktex.cnf} \NC\NR -\NC \type{\pdfuniqueresname} \NC integer \NC 0 \NC \NC\NR -\NC \type{\pdfprotrudechars} \NC integer \NC 0 \NC \NC\NR -\NC \type{\pdfgentounicode} \NC integer \NC 0 \NC \NC\NR -\NC \type{\pdfmajorversion} \NC integer \NC 1 \NC output \PDF\ 1.4 by default \NC\NR -\NC \type{\pdfminorversion} \NC integer \NC 4 \NC \PDF\ 1.4 \NC\NR -\NC \type{\pdfpagebox} \NC integer \NC 0 \NC \NC\NR -\NC \type{\pdfforcepagebox} \NC integer \NC 0 \NC \NC\NR -\NC \type{\pdfinclusionerrorlevel} \NC integer \NC 0 \NC \NC\NR -%----------------------------------------------------------------------- -\NC \type{\pdfhorigin} \NC dimension \NC 1\,in \NC \NC\NR -\NC \type{\pdfvorigin} \NC dimension \NC 1\,in \NC \NC\NR -\NC \type{\pdfpagewidth} \NC dimension \NC 0\,pt \NC \NC\NR -\NC \type{\pdfpageheight} \NC dimension \NC 0\,pt \NC \NC\NR -%\NC \type{\pdffirstlineheight} \NC dimention \NC -1000\,pt \NC \NC\NR -%\NC \type{\pdflastlinedepth} \NC dimention \NC -1000\,pt \NC \NC\NR -%\NC \type{\pdfeachlineheight} \NC dimention \NC -1000\,pt \NC \NC\NR -%\NC \type{\pdfeachlinedepth} \NC dimention \NC -1000\,pt \NC \NC\NR -\NC \type{\pdflinkmargin} \NC dimension \NC 0\,pt \NC \NC\NR -\NC \type{\pdfdestmargin} \NC dimension \NC 0\,pt \NC \NC\NR -\NC \type{\pdfthreadmargin} \NC dimension \NC 0\,pt \NC \NC\NR -\NC \type{\pdfmapfile} \NC text \NC \filename{pdftex.map} \NC not dumped\NC\NR +\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][tbl:configparms] - {The set of \PDFTEX\ configuration parameters.} +\placetable + [here][flags] + {The meaning of flags in the font descriptor.} {\getbuffer} -\startbuffer -\tx\setupinterlinespace -\startframedtext -\starttyping -% tex-ini-files 2016-04-15: pdftexconfig.tex +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. -% Load shared (PDF) settings in pdfTeX +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. -% Enable PDF output -\pdfoutput = 1 +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. -% Paper size: dimensions given in absolute terms -\pdfpageheight = 11 true in -\pdfpagewidth = 8.5 true in +\stopnarrower -% Enable PDF 1.5 output and thus more compression -\pdfminorversion = 5 -\pdfobjcompresslevel = 2 +If the {\em fontflags} field is not given, and the font is embedded, +\PDFTEX\ treats it as the value~4 (decimal, that is, bit position 3 is set), +a symbolic font. For non-embedded fonts, the default value is +\type{0x22}, a non-symbolic serif font. If you do not know the correct +value, it is best not to specify it at all, as specifying a bad value of +font flags may cause trouble in viewers. On the other hand this option +is not absolutely useless because it provides backward compatibility +with older map files (see the {\em fontfile} description below). -% Low-level settings unlikely ever to need to change -\pdfcompresslevel = 9 -\pdfdecimaldigits = 3 -\pdfpkresolution = 600 -\pdfhorigin = 1 true in -\pdfvorigin = 1 true in -\stoptyping -\stopframedtext -\stopbuffer +\stopdescription -\placefigure[here][in:pdftexconfig] - {\PDFTEX\ configuration file for \TEXLIVE\ (\filename{pdftexconfig.tex}).} - {\getbuffer} +\startdescription {special} +specifies font manipulations in the same way as +\type{dvips}. Currently only the keywords \type{SlantFont} +and \type{ExtendFont} are interpreted, other instructions (notably +\type{ReEncodeFont} and its parameters, see {\em encoding} below) are +just ignored. The permitted \type{SlantFont} range is $-$1..1; +for \type{ExtendFont} it's $-$2..2. The block of {\em special} +instruction must be enclosed by double quote characters: \type{"}. -Independent of whether such a configuration file is read or not, the -first action in a \PDFTEX\ run is that the program reads the global -\WEBC\ configuration file (\filename{texmf.cnf}), which is common to all -programs in the \WEBC\ system. This file mainly defines file search -paths, the memory layout (\eg\ string pool and hash size), and a few -other general parameters. +\stopdescription -%*********************************************************************** +\startdescription {encodingfile} specifies the name of the file +containing the external encoding vector to be used for the font. The +encoding file name must have the extension \type{.enc}, and the file +name including extension must be given with either a preceding~\type{<} +character or a preceding~\type{<[}. The format of the encoding vector is +identical to that used by \type{dvips}. If no encoding is specified, the +font's built||in default encoding is used. The {\em encodingfile} field +may be omitted if you are sure that the font resource has the correct +built||in encoding. In general this option is highly recommended, and it +is {\em required} when subsetting a TrueType font. -\subsection{Creating format files} +Starting with version 1.40.19, an encoding file can also be specified +for bitmap \PK\ fonts. In this case, it assigns the glyph names from the +given encoding vector, which can be used with the +\type{\pdfglyphtounicode} primitive (q.v.). For example: -\startbuffer -\tx\setupinterlinespace -\startframedtext \starttyping -% Thomas Esser, 1998. public domain. -\input etex.src -\dump -\endinput +\pdfglyphtounicode{ffi}{0066 0066 0069} % normally: \input glyphtounicode +\pdfgentounicode=1 +\pdfmapline{cmb10 <7t.enc} +\font\cmb=cmb10 \cmb ffi \stoptyping -\stopframedtext -\stopbuffer -\placefigure[here][in:etexini] - {File \type{etex.ini} for the plain \ETEX\ format with \DVI\ output.} - {\getbuffer} +The result is a \PDF\ file with a correctly-labeled \type{/ffi} +character instead of the numeric character position in the +\type{cmb10.tfm} (decimal 14). -\startbuffer -\tx\setupinterlinespace -\startframedtext -\starttyping -% Thomas Esser, 1998. public domain. -% This is used for pdftex and pdfetex, which are now identical: both -% with e-TeX extensions, both with pdf output. -\input pdftexconfig.tex -\input etex.src -\input pdftexmagfix.tex -\dump -\endinput -\stoptyping -\stopframedtext -\stopbuffer +\stopdescription -\placefigure[here][in:pdfetexini] - {File \type{pdfetex.ini} for plain \ETEX\ with \PDF\ output.} - {\getbuffer} +\startdescription {fontfile} +sets the name of the font file to be embedded into the \PDF\ output for a +given \TeX\ font (the {\em tfmname}~$\leftrightarrow$~{\em fontfile} +mapping is the most prominent use of the \filename{pdftex.map} file). +The font file name must belong to a Type~1 or TrueType font file. If +the {\em fontfile} field is missing, no font embedding can take place; +in case the {\em psname} field does not contain one of the 14 standard +font names also a warning will be given. Not embedding a font into a \PDF\ +file might be troublesome, as it requires that the font or some similar +looking replacement font is available within the \PDF\ viewer, so that +it can render the glyphs with its own font version. -\startbuffer -\tx\setupinterlinespace -\startframedtext -\starttyping -% Thomas Esser, 1998. public domain. -\input pdftexconfig.tex -\scrollmode -\input latex.ltx -\endinput -\stoptyping -\stopframedtext -\stopbuffer +The font file name should be preceded by one or two special characters, +specifying how to handle the font file: -\placefigure[here][in:pdflatexini] - {File \type{pdflatex.ini} for the \LATEX\ format with \PDF\ output.} - {\getbuffer} +\startitemize -The \PDFTEX\ engine supports building formats for \DVI\ and \PDF\ output -in the same way as the classical \TEX\ engine does for \DVI. Format -generation (and other \type{initex} features) is enabled by the -\type{-ini} option. The default mode (\DVI\ or \PDF) can be chosen -either on the command line by setting the option \type{-output-format} -to \type{dvi} or \type{pdf}, or by setting the \type{\pdfoutput} -parameter. The format file then inherits this setting, so that a later -invocation of \PDFTEX\ with this format starts in the preselected mode -(which still can be overridden). A format file can be read in only by -the engine that has generated it; a format incompatible with an engine -leads to a fatal error. +\item If the font file name is preceded by a \type{<} character, the + font file will be only partially embedded in the \PDF\ output + (``subsetted''), meaning that only used glyphs are written to + the \PDF\ file. This is the most common use and is {\em strongly + recommended} for any font, as it ensures the portability and + reduces the size of the \PDF\ output. Subsetted fonts are included + in such a way that name and cache clashes are minimized. -It is customary to package the configuration and macro file input -into a \type{.ini} file. \Eg, the file \type{etex.ini} in -\in{figure}[in:etexini] is for generating an \ETEX\ format with \DVI\ -output. It has been traditional for many years to generate -\type{etex.fmt} with \PDFTEX\ rather than the original \ETEX, because -\PDFTEX\ contains a few additional programming and other -non-\PDF-related features on which people have come to rely. +\item If the font file name is preceded by a double \type{<<}, the font + file will be included entirely --- all glyphs of the font are + embedded, including even those not used in the document. Apart + from causing large size \PDF\ output, this option may cause + troubles with TrueType fonts, so it is normally not recommended + for Type~1 or TrueType fonts. But this is currently the only mode + that allows the use of OpenType fonts. This mode might also be + useful in case the font is atypical and cannot be subsetted well + by \PDFTEX. {\em Beware: proprietary font vendors typically + forbid full font inclusion.} -The \type{pdfetex.ini} file \in{figure}[in:etexini] shows the -corresponding format with \PDF\ output by default; this is what creates -the format file read when \type{pdftex} is normally invoked. +\item If no special character precedes the font file name, it is + ignored, with a warning (this case was deprecated in \PDFTEX\ + version 1.40.0). You achieve exactly the same \PDF\ result if you + just remove the font file name from the map entry. Then the glyph + widths that go into the \PDF~file are extracted from the + \TFM~file, and a font descriptor object is created that contains + approximations of the font metrics for the selected font. -Finally, \type{pdflatex.ini} \in{figure}[in:pdflatexini] shows how the -\LATEX\ format with \PDF\ output by default is generated. +\item Specifying the {\em psname} and no font file name is only useful + as a last-ditch fallback when you do not want to embed the font + (\eg\ due to font license restrictions), but wish to use the font + metrics and let the \PDF\ viewer generate instances that look + close to the used font in case the font resource is not installed + on the system where the \PDF\ output will be viewed or + printed. To use this feature, the font flags {\em must} be + specified, and it must have the bit~6 set on, which means that + only fonts with the Adobe Standard Roman Character Set can be + simulated. The only exception is the case of a symbolic font, + which is not very useful. -The corresponding \PDFTEX\ calls for format generation are: +\stopitemize + +If you encounter problematic lookups, for instance if \PDFTEX\ tries +to open a \type{.pfa} file instead of a \type{.pfb}, you can add +the suffix to the filename. In this respect, \PDFTEX\ completely relies +on the \type{kpathsea} library. + +\stopdescription + +For Type~1 and TrueType fonts, the font file will be included only once +in the \PDF\ output, regardless of how many \TeX\ \type{\font} instances +are used in the document. For instance, given \starttyping -pdftex -ini *etex.ini -pdftex -ini *pdfetex.ini -pdftex -ini *pdflatex.ini +\font\a = cmr12 +\font\b = cmr12 at 11pt \stoptyping -These calls produce format files \filename{etex.fmt}, -\filename{pdfetex.fmt}, and \filename{pdflatex.fmt}, as the default -format file name is taken from the input file name. You can override -this with the \type{-jobname} option. The asterisk \type{*} before the -file name is an unusual flag, only used in \type{-ini} mode, which -causes the \PDFTEX\ engine to enable \ETEX's features. - -Incidentally, as of \PDFTEX\ 1.40.21 (\TEX\ Live 2020), \filename{.fmt} -files are compressed with \type{zlib}. This makes for a considerable -savings in space, and consequently in time. +the outline file \type{cmr12.pfb} will only be included once in the +\PDF, and merely scaled down to create the instance for \type{\b}. -\subsection{Testing the installation} +If a used font is not present in the map files, \PDFTEX\ will try to use +\PK~fonts as most \DVI\ drivers do, creating \PK~fonts on||the||fly if +needed. This is the normal, and recommended, way to use bitmap fonts. -When everything is set up, you can test the installation. A simple test -of plain \PDFTEX\ is: +To summarize this rather confusing story, we include some example map +lines. The most common way is to embed only a subset of glyphs from a +font for a particular desired encoding, like this: \starttyping -pdftex story \\end +ptmri8r Times-Italic <8r.enc -o +\stoptyping -%*********************************************************************** +A TrueType file can be recognized by its suffix \filename {ttf}. The optional +{\em encoding} specifies the encoding, which is the same as the encoding +vector used in map files for \PDFTEX\ and \type{dvips}. If the encoding is +not given, all the glyphs of the \AFM\ output will be mapped to \type +{/.notdef}. \type{ttf2afm} writes the output \AFM\ to standard output. If we +need to know which glyphs are available in the font, we can run \type +{ttf2afm} without encoding to get all glyph names. The resulting \AFM\ file +can be used to generate a \TFM\ one by applying \filename {afm2tfm}. -\section{Invoking \PDFTEX} +To use a new TrueType font the minimal steps may look like below. We suppose +that \filename {test.map} is used. -\PDFTEX\ has many command line options. Except for the simple and -rarely-used \type{-draftmode} and \type{-output-format} options, they -are all inherited from the common framework for \TeX\ engines as -implemented in \WEBC\ (its manual is available at \from [web2c]). - -The same commonality holds for environment variables; see the section -``Setting search paths'' above for an overview. Two additional -environment variables need more description here: first, -\type{SOURCE_DATE_EPOCH} (introduced in version 1.40.17, 2016). If this -is set, it must be a positive integer (with one trivial exception: if it -is set but empty, that is equivalent to 0). Non-integer values cause a -fatal error. The value is used as the current time in seconds since the -usual Unix ``epoch'': the beginning of 1970-01-01, UTC. Thus, a value -of \type{32} would result in a \type{/CreationDate} and \type{/ModDate} -values of \type{19700101000032Z}. This is useful for reproducible -builds of documents. (See also \type{\pdfinfoomitdate}, -\type{\pdfsuppressptexinfo}, et al.) +\starttyping +ttf2afm -e 8r.enc -o times.afm times.ttf +afm2tfm times.afm -T 8r.enc +echo "times TimesNewRomanPSMT <8r.enc >test.map +\stoptyping -The second, related, environment variable is \type{FORCE_SOURCE_DATE}. -If this is set to~\type{1}, \TEX's time-related primitives are also -initialized from the value of \type{SOURCE_DATE_EPOCH}. These primitives -are \type{\year}, \type{\month}, \type{\day}, and \type{\time}. If -\type{SOURCE_DATE_EPOCH} is not set, setting \type{FORCE_SOURCE_DATE} -has no effect. If \type{FORCE_SOURCE_DATE} is unset, set to the empty -string, or set to~\type{0}, the primitives reflect the current time as -usual. Any other value elicits a warning, and the current time is used. -This is useful if one wants to make reproducible \PDF{}s for a set -of documents without changing them in any way, e.g., an operating system -distribution with manuals that use \type{\today}. Except in such unusual -circumstances, it is better not to set this, and let the \TEX\ -primitives retain the meaning they have always had. +There are a few limitations with TrueType fonts in comparison with +Type~1 fonts: -In addition, if both \type{SOURCE_DATE_EPOCH} and -\type{FORCE_SOURCE_DATE} are set, \type{\pdffilemoddate} returns a value -in UTC, ending in \type{Z}. (The values of the environment variables are -irrelevant in this case.) +\startitemize[a,packed] +\item The special effects SlantFont|/|ExtendFont did not work + before version 1.40.0. +\item To subset a TrueType font, the font must be specified as re||encoded, + therefore an encoding vector must be given. +\item TrueType fonts coming with embedded \PDF\ files are kept + untouched; they are not replaced by local ones. +\stopitemize -Finally, just to have the list of options and basic invocation at hand, -here is a verbatim listing of the \type{-}\type{-help} output. All -options can be specified with one or two dashes and unambiguously -abbreviated. +For much more about \PDFTEX\ and TrueType fonts, including many details +on handling glyph names, see ``A closer look at TrueType fonts and +\PDFTEX'', {\em TUGboat} 30:1 (2009), pp.~32||34, \from[thanh_truetype_tub] -\startnotmode[screen] - \switchtobodyfont[9pt] % squeeze everything on one page -\stopnotmode +%*********************************************************************** -\typefile{pdftex-help.txt} +\section{Formal syntax specification} -\startnotmode[screen] - \switchtobodyfont[10pt] % squeeze everything on one page -\stopnotmode +This section formally specifies the \PDFTEX-specific extensions to the +\TEX\ macro programming language. Most primitives are prefixed by +\type{pdf}. The general definitions and syntax rules follow after the +list of primitives. -%*********************************************************************** +Two new units of measure were introduced in \PDFTEX\ 1.30.0: the +new Didot (1\,nd~=~0.375\,mm) and the new Cicero (1\,nc~=~12\,nd) +(the former was proposed by \ISO\ in 1975). -\section{Macro packages supporting \PDFTEX} +% Generated list of primitives (see Makefile). +\input pdftex-syntax.tex -As \PDFTEX\ generates the final \PDF\ output without help of -a postprocessor, macro packages that take care of these \PDF\ features -have to be set up properly. Typical tasks are handling color, -graphics, hyperlink support, threading, font||inclusion, as well as -page imposition and manipulation. All these \PDF||specific tasks can be -controlled by \PDFTEX's own primitives (a few also by a \PDFTEX||specific -\type{\special{pdf: ...}} primitive). Any other \type{\special{}} commands, -like the ones defined for various \DVI\ postprocessors, are simply -ignored by \PDFTEX\ when in \PDF\ output mode; a warning is given only -for non||empty \type{\special{}} commands. +\subsubject{General definitions and syntax rules} -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 +\startpacked -\starttyping -\pdfoutput=1 \let\special\message -\stoptyping +%%S NL +%%S Syntax rules: -or, if this leads to confusion, +\Syntax{ +\Something{general text} \Means % + \Lbrace \Something{balanced text} \Rbrace +} -\starttyping -\pdfoutput=1 \def\special#1{\write16{special: #1}} -\stoptyping +\Syntax{ +\Something{attr spec} \Means % + \Literal{attr} \Something{general text} +} -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. +\Syntax{ +\Something{resources spec} \Means % + \Literal{resources} \Something{general text} +} -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. +\Syntax{ +\Something{rule spec} \Means % + (\Literal{width} \Or \Literal{height} \Or \Literal{depth}) % + \Something{dimen} \Optional{\Something{rule spec}} +} -\startitemize +%\Syntax{\Something{object type spec} \Means +% \Optional{\Literal{stream} +% \Optional{\Something{attr spec}}} \Something{object contents}} -\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. +\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} +} -\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. +\Syntax{ +\Something{annot type spec} \Means % + \Literal{reserveobjnum} + \Or \Next % + \Optional{\Literal{useobjnum} \Something{number}} % + \Optional{\Something{rule spec}} % + \Something{general text} +} -\item The \CONTEXT\ macro package by Hans Hagen has very full support - for \PDFTEX\ in its generalized hypertext features. Support for - \PDFTEX\ is implemented as a special driver, and is invoked by - typing \type{\setupoutput[pdftex]} or feeding \TEXEXEC\ with the - \hbox{\tt -{}-pdf} option. +\Syntax{ +\Something{object contents} \Means % + \Something{file spec} + \Or \Something{general text} +} -\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}. +\Syntax{ +\Something{xform attr spec} \Means % + \Optional{\Something{attr spec}} \Optional{\Something{resources spec}} +} -\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. +\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}} +} -\stopitemize +\Syntax{ +\Something{outline spec} \Means % + \Optional{\Something{attr spec}} % + \Something{action spec} % + \Optional{\Literal{count} \Something{number}} % + \Something{general text} +} -Some nice samples of \PDFTEX\ output can be found at -\from[ptex_org], \from[context], and \from[tex_showcase]. +\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} +} -\section{Setting up fonts} +\Syntax{ +\Something{goto-action struct spec} \Means % + \Literal{struct} (\Something{numid} \Or \Literal{nameid} \Or \Something{general text}) +} -\PDFTEX\ can work with Type~1 and TrueType fonts (and to some extent -also with OpenType fonts). Font files should be available and embedded -for all fonts used in the generated PDF. It is possible to use -\METAFONT||generated fonts in \PDFTEX\ --- but it is strongly -recommended not to use these fonts if an equivalent is available in -Type~1 or TrueType format, if only because bitmap Type~3 fonts render -poorly under enlargement. +% keep in sync with redundant copy below. +\Syntax{ +\Something{goto-action spec} \Means % + \Optional{\Something{goto-action struct spec}} \Something{numid} + \Or \Next \Optional{\Something{file spec}} \Optional{\Something{goto-action struct spec}} \Something{nameid} + \Or \Next \Optional{\Something{file spec}} \Optional{\Something{goto-action struct spec}} \Optional{\Something{page spec}} \Something{general text} + \Or \Next \Something{file spec} \Optional{\Something{goto-action struct spec}} \Something{nameid} \Something{newwindow spec} + \Or \Next \Something{file spec} \Optional{\Something{goto-action struct 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} +} -\subsection[mapfile]{Map files} +\Syntax{ +\Something{colorspace spec} \Means % + \Literal{colorspace} \Something{number} +} -Font map files provide the connection between \TEX\ \TFM\ font files -and outline font file names. They contain also information about -re||encoding arrays, partial font embedding (``subsetting''), and -character transformation parameters (like SlantFont and ExtendFont). Those -map files were first created for \DVI\ postprocessors. But, as \PDFTEX\ -in \PDF\ output mode includes all \PDF\ processing steps, it also needs -to know about font mapping, and therefore reads in one or more map files. -Map files are not read in when \PDFTEX\ is in \DVI\ mode. Bitmap fonts -can (and normally should) be used without being listed in the map file. +\Syntax{ +\Something{pdf box spec} \Means % + \Literal{mediabox} % + \Or \Literal{cropbox} % + \Or \Literal{bleedbox} % + \Or \Literal{trimbox} % + \Or \Literal{artbox} +} -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. +\Syntax{ +\Something{map spec} \Means % + \Lbrace \Optional{\Something{map modifier}} % + \Something{balanced text} \Rbrace +} -Within the map file, each font is listed on a single line. The syntax of -each line is upward||compatible with \type{dvips} map files and can contain -the following fields (some are optional; explanations follow): +\Syntax{ +\Something{map modifier} \Means % + \Literal{+} \Or \Literal{=} \Or \Literal{-} +} -\startnarrower -{\em tfmname psname fontflags special encodingfile fontfile} -\stopnarrower +\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 % + \Optional{\Literal{struct} \Something{number}} \\ + (\Something{numid} \Or \Something{nameid}) + \Something{dest type} +} + +\Syntax{ +\Something{dest type} \Means % + \Literal{xyz} \Optional{\Literal{zoom} \Something{number}} + \Or \Literal{fitr} \Something{rule spec} + \Or \Next \Literal{fitbh} + \Or \Literal{fitbv} + \Or \Literal{fitb} + \Or \Literal{fith} + \Or \Literal{fitv} + \Or \Literal{fit} +} + +\Syntax{ +\Something{thread spec} \Means % + \Optional{\Something{rule spec}} % + \Optional{\Something{attr spec}} % + \Something{id spec} +} + +\Syntax{ +\Something{id spec} \Means % + \Something{numid} \Or \Something{nameid} +} + +\Syntax{ +\Something{file spec} \Means % + \Literal{file} \Something{general text} +} + +\Syntax{ +\Something{page spec} \Means % + \Literal{page} \Something{number} +} + +\Syntax{ +\Something{expand spec} \Means % + \Something{stretch} % + \Something{shrink} % + \Something{step} % + \Optional{\Literal{autoexpand}} +} + +\Syntax{ +\Something{stretch} \Means % + \Something{number} +} + +\Syntax{ +\Something{shrink} \Means % + \Something{number} +} + +\Syntax{ +\Something{step} \Means % + \Something{number} +} + +\Syntax{ +\Something{pre spec} \Means % + \Literal{pre} +} + +\Syntax{ +\Something{pdfliteral spec} \Means % + \Literal{direct} \Or \Literal{page} +} + +\Syntax{ +\Something{pdfspecial spec} \Means % + \Lbrace \Optional{\Something{pdfspecial id} % + \Optional{\Something{pdfspecial modifier}}} % + \Something{balanced text} \Rbrace +} + +\Syntax{ +\Something{pdfspecial id} \Means % + \Literal{pdf:} \Or \Literal{PDF:} +} + +\Syntax{ +\Something{pdfspecial modifier} \Means % + \Literal{direct:} +} + +\Syntax{ +\Something{stack action} \Means % + \Literal{set} \Or \Literal{push} \Or \Literal{pop} \Or \Literal{current} +} + +\stoppacked + +A \Something{general text} is expanded immediately, like \type{\special} +in traditional \TEX, unless explicitly mentioned otherwise. + +Some of the object and image related primitives can be prefixed by +\type{\immediate}. More about that in the next sections. + +%*********************************************************************** + +\section[primitives]{\PDFTEX\ primitives} + +Here follows a description of the primitives added by \PDFTEX\ to the +original \TEX\ engine (other extensions by \ETEX, \MLTEX\ and \ENCTEX\ +are not listed). Many of these primitives are described further in the +\filename {samplepdf.tex} file in the \PDFTEX\ distribution. + +If the output is \DVI, then the \PDFTEX-specific dimension parameters +are not used at all. However, some \PDFTEX\ integer parameters can +affect \DVI\ as well as \PDF\ output (specifically, \type{\pdfoutput} and +\type{\pdfadjustspacing}). + +%A warning to macro writers: The \PDFTEX-team reserves the namespaces +%\type{\pdf*} and \type{\ptex*} for use by \PDFTEX; if you define macros +%whose names start with \type{\pdf} or \type{\ptex}, you risk nameclashes +%with new primitives introduced in future versions of \PDFTEX. + +General warning: many of these new primitives, for example +\type{\pdfdest} and \type{\pdfoutline}, write their arguments directly +to the \PDF\ output file (when producing \PDF), as \PDF\ string +constants. This means that {\em you} (or, more likely, the macros you +write) must escape characters as necessary (namely \type{\}, \type{(}, +and \type{)}. Otherwise, an invalid \PDF\ file may result. The +\type{hyperref} and \TEXINFO\ packages have code which may serve as +a starting point for implementing +this, although it will certainly need to be adapted to any particular +situation. + +%*********************************************************************** + +\subsection{Document setup} + +\pdftexprimitive{\Syntax{\Tex{\pdfoutput} \Whatever{integer}}} +\bookmark{\tex{pdfoutput}} + +This parameter specifies whether the output format should be \DVI\ or +\PDF. A positive value means \PDF\ output, otherwise (default 0) one gets +\DVI\ output. This primitive is the only one that must be set to produce +\PDF\ output (unless the commandline option \type{-output-format=pdf} +is used); all other primitives are optional. This parameter cannot be +specified {\em after} shipping out the first page. In other words, if +we want \PDF\ output, we have to set \type{\pdfoutput} before \PDFTEX\ +ships out the first page. + +When \PDFTEX\ starts complaining about specials, one can be rather sure +that a macro package is not aware of the \PDF\ mode. A simple way of +making macros aware of \PDFTEX\ in \PDF\ or \DVI\ mode is: + +\starttyping +\ifx\pdfoutput\undefined \csname newcount\endcsname\pdfoutput \fi +\ifcase\pdfoutput DVI CODE \else PDF CODE \fi +\stoptyping + +Using the \type{ifpdf.sty} file, which works with both \LATEX\ and plain +\TeX, is a cleaner way of doing this. Historically, the simple test +\type{\ifx\pdfoutput\undefined} was defined; but nowadays, the \PDFTEX\ +engine is used in distributions also for non-\PDF\ formats (\eg\ +\LATEX), so \type{\pdfoutput} may be defined even when the output format +is \DVI. + +\pdftexprimitive{\Syntax{\Tex{\pdfmajorversion} \Whatever{integer}}} +\bookmark{\tex{pdfmajorversion}} + +\pdftexprimitive{\Syntax{\Tex{\pdfminorversion} \Whatever{integer}}} +\bookmark{\tex{pdfminorversion}} + +Together, these two primitives specify the \PDF\ version for generated \PDF\ +output. The defaults compiled into the \PDFTEX\ program are +\type{\pdfmajorversion=1} and \type{\pdfminorversion=4}, thus \PDF~1.4 +is generated by default. + +However, distributions typically alter the engine's compiled default +minor version of~4 when building formats. For example, as of 2010, +\TEXLIVE\ sets \type{\pdfminorversion=5} when formats are built. This is +so object compression can be enabled (see \type{\pdfobjcompress} below). + +This value also defines the highest \PDF\ version for included \PDF{}s +to be allowed without error, by default (see +\type{\pdfinclusionerrorlevel}). + +The values for both must be $\ge\,1$ but are not checked further. +Furthermore, they are set independently; only setting +\type{\pdfmajorversion=2} would result in \PDF~2.4 output; it's +necessary to additionally set \type{\pdfminorversion}. + +If specified, these primitives must appear before any data is to be +written to the generated \PDF\ file. The \type{\pdfmajorversion} +primitive was introduced in \PDFTEX\ 1.40.21. \type{\pdfminorversion} +was originally a shortened synonym of the +\type{\pdfoptionpdfminorversion} command, which is now obsolete. +\introduced{1.30.0} + +\pdftexprimitive{\Syntax{\Tex{\pdfcompresslevel} \Whatever{integer}}} +\bookmark{\tex{pdfcompresslevel}} + +This integer parameter specifies the level of {\em stream} compression +(text, inline graphics, and embedded \PNG\ images (only if they are un- +and re-compressed during the embedding process); all done by the +\type{zlib} library). Zero means no compression, 1~means fastest, +9~means best, $2..8$ means something in between. A value outside this +range will be adjusted to the nearest meaningful value. This parameter +is read each time \PDFTEX\ starts a stream. Setting +\type{\pdfcompresslevel=0} is useful for \PDF\ stream debugging. + +\pdftexprimitive{\Syntax{\Tex{\pdfobjcompresslevel} \Whatever{integer}}} +\bookmark{\tex{pdfobjcompresslevel}} + +This integer parameter controls the compression of {\em non-stream} +objects. If specified, the parameter must appear before any data is +written to the \PDF\ output. \introduced{1.40.0} + +In the \PDF-1.4 specification, non-stream objects had to be written in +the \PDF\ file as clear text, uncompressed. The \PDF-1.5 specification +allows collecting non-stream objects as ``compressed objects'' into +``object stream'' objects (\type{/Type /ObjStm}, see \PDF\ Ref.\ +5th~ed., sect.~3.4.6). At the end of the \PDF\ file, an \type{/XRef} +cross-reference stream is then written out instead of the object table. +This can result in a considerably smaller \PDF\ file, particularly if +lots of annotations and links are used. + +The writing of compressed objects is enabled by setting +\type{\pdfobjcompresslevel} to a value between~1 and~3; it's disabled +if~0 (default). Object compression also requires that +\type{\pdfminorversion}$\,\ge\,$5 (or +\type{\pdfmajorversion}$\,\ge\,$2), else a warning is given and the +compression 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: +\startitemize[0,packed] +\item When set to~0, no object streams are generated at all. +\item 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. +\item 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. +\item Finally, when set to~3, all non-stream objects +are compressed, including the \type{/Info} dictionary (this means that +the \type{/Info} can't be read as clear text any more). If object streams +are to be used, currently \type{\pdfobjcompresslevel=2} is recommended, +and is so specified in some distributions, including \TEXLIVE~2010 and later. +\stopitemize -It is mandatory that {\em tfmname} is the first field. If a {\em -psname} is given, it must be the second field. Similarly if {\em -fontflags} is given it must be the third field (if {\em psname} is -present) or the second field (if {\em psname} is left out). The -positions of {\em special}, {\em encodingfile}, and {\em fontfile} can -be mixed. +\description{Compatibility caveat:} \PDF\ files generated with object +streams enabled can't be read with (sufficiently old) \PDF\ viewers that +don't understand \PDF-1.5 files. For widest distribution and unknown +audience, don't activate object stream writing. The \PDF-1.5 standard +describes also a hybrid object compression mode that gives some backward +compatibility, but this is currently not implemented, as \PDF-1.5 was +rather quickly adopted by modern \PDF\ viewers. Also not implemented is +the optional \type{/Extends} key. -\startdescription {tfmname} -sets the name of the \TFM\ file for a font --- the file name given in a -\TEX\ \type{\font} command. This name must always be given. +\pdftexprimitive{\Syntax{\Tex{\pdfdecimaldigits} \Whatever{integer}}} +\bookmark{\tex{pdfdecimaldigits}} -\stopdescription +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. -\startdescription {psname} -sets the (\POSTSCRIPT) base font name, which has two uses: +When including huge \METAPOST\ images using \filename {supp-pdf.tex}, one can +limit the accuracy to two digits by typing: \type{\twodigitMPoutput}. -First, when a \PDF\ file is embedded by \type{\pdfximage}, the -\type{/BaseFont} names in the font dictionaries of Type~1 and Type~1C -(CFF) fonts from the embedded \PDF\ file are checked against this {\em -psname} field. If names match, the glyphs of that font will not be -copied from the embedded \PDF\ file, but instead a local font is opened, -and all needed glyphs will be taken from the Type~1 font file that is -mentioned in the map line (see {\em fontfile} below). By this collecting -mechanism Type~1 glyphs can be shared between several embedded \PDF\ -files and with text that is typeset by \PDFTEX, which helps keeping the -resulting \PDF\ file size small, if many files with similar Type~1(C) -fonts are embedded. Replacing Type~1 fonts from embedded \PDF\ files -requires that also a Type~1 font file name is in the {\em fontfile} field -(see below). +\pdftexprimitive{\Syntax{\Tex{\pdfhorigin} \Whatever{dimen}}} +\bookmark{\tex{pdfhorigin}} -Second, if a font file is not to be embedded into the \PDF\ output -({\em fontfile} field missing), then the {\em psname} field will be -copied to the \type{/BaseFont} and \type{/FontName} dictionary entries -in the \PDF\ file, so that the \POSTSCRIPT\ font name will be known to -reading applications (\eg\ viewers). +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. -It is highly recommended to use the {\em psname} field, but -strictly speaking it is optional. +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. -\stopdescription +\pdftexprimitive{\Syntax{\Tex{\pdfvorigin} \Whatever{dimen}}} +\bookmark{\tex{pdfvorigin}} -\startdescription {fontflags} -optionally specify some characteristics of the font. The following description of -these flags is taken, with slight modification, from the \PDFReference\ -(the section on font descriptor flags). Viewers can adapt their rendering -to these flags, especially when they substitute a non-embedded font by -some own approximation. +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). -\startnarrower +\pdftexprimitive{\Syntax{\Tex{\pdfpagewidth} \Whatever{dimen}}} +\bookmark{\tex{pdfpagewidth}} -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. +This dimension parameter specifies the page width of the \PDF\ output +(the screen, the paper, etc.). \PDFTEX\ reads this parameter when it +starts shipping out a page. After magnification has been changed by +the \type{\mag} primitive, check that this parameter reflects the wished +true page width. + +If the value is set to zero, the page width is calculated as +$w_{\hbox{\txx box being shipped out}} + 2 \times (\hbox{horigin} + +\hbox{\type{\hoffset}})$. When part of the page falls off the paper or +screen, you can be rather sure that this parameter is set wrong. + +\pdftexprimitive{\Syntax{\Tex{\pdfpageheight} \Whatever{dimen}}} +\bookmark{\tex{pdfpageheight}} + +Similar to the previous item, this dimension parameter specifies the +page height of the \PDF\ output. If set to zero, the page height will +be calculated analogously to the above. After magnification has been +changed by the \type{\mag} primitive, check that this parameter reflects +the wished true page height. + +%*********************************************************************** + +\subsection[sec.docinfocatalog]{Document info and catalog} + +\pdftexprimitive{\Syntax{\Tex{\pdfinfo} \Something{general text}}} +\bookmark{\tex{pdfinfo}} + +This primitive allows the user to specify information for the document +info dictionary; if this information is provided, it can be extracted, +\eg\ by the \type{pdfinfo} program. The \Something{general text} is a +collection of key||value||pairs. The key names are preceded by a +\type{/}, and the values, being strings, are given between +parentheses. All keys, and the primitive itself, are optional. Possible +keys are:\crlf +\type{/Title},\crlf +\type{/Author},\crlf +\type{/Subject},\crlf +\type{/Keywords},\crlf +\type{/Producer} (defaults to \hbox{\tt pdfTeX-\currentpdftex}),\crlf +\type{/Creator} (defaults to \type{TeX}),\crlf +\type{/CreationDate} (defaults to current date and time, with time zone),\crlf +\type{/ModDate} (same default),\crlf +\type{/Trapped} (defaults to \type{/False},\crlf +\type{/PTEX.Fullbanner} (defaults to the \type{\pdftexbanner} string, q.v.). + +\type{/CreationDate} and \type{/ModDate} are expressed in the form +\type{D:YYYYMMDDhhmmssTZ}, where \type{YYYY} is the year, \type{MM} is +the month, \type{DD} is the day, hh is the hour, \type{mm} is the +minutes, \type{ss} is the seconds, and \type{TZ} is an optional string +denoting the time zone, \type{Z} for universal time. For example, this +is the Unix epoch, the beginning of 1970-01-01 UTC, in this format: +\type{19700101000000Z}. If the time zone is not UTC, it is given as +\type{+HH'mm'} or \type{-HH'mm'}, indicating an offset of the given +hours and minutes from UTC, with the given either later (\type{+}) or +earlier (\type{-}) than UTC. (This syntax is specified by the PDF +definition.) + +Multiple appearances of \type{\pdfinfo} are concatenated. Usually if a +key is given more than once, the first appearance will be used, but this +is viewer||dependent. Except for standard \TeX\ expansion, \PDFTEX\ does +not perform any further operations in the \Something{general text} +provided by the user. + +Here is an example of using \type{\pdfinfo} to include the +information not supplied by \PDFTEX: + +\starttyping +\pdfinfo { + /Title (example.pdf) + /Author (Tom and Jerry) + /Subject (Example) + /Keywords (mouse, cat) +} +\stoptyping + +For more details on all this, see the \PDFReference. + +\pdftexprimitive{\Syntax{\Tex{\pdfinfoomitdate} \Whatever{integer}}} +\bookmark{\tex{pdfinfoomitdate}} + +If nonzero, omit the \type{/CreationDate} and \type{/ModDate} keys from +the document info dictionary described above. This can be useful in +making reproducible \PDF{}s. \introduced{1.40.17} + +\pdftexprimitive{\Syntax{\Tex{\pdfsuppressptexinfo} \Whatever{integer}}} +\bookmark{\tex{pdfsuppressptexinfo}} + +Treated as a bitmask, specifying which \type{PTEX.*} keys to omit from +the output: \startbuffer -\starttabulate[|c|l|] +\starttabulate[|l|l|] \HL -\NC \bf bit position \NC \bf semantics \NC\NR +\NC \bf value \NC \bf suppresses \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 +\NC \tt 1 \NC \type{PTEX.Fullbanner} \NC\NR +\NC \tt 2 \NC \type{PTEX.FileName} \NC\NR +\NC \tt 4 \NC \type{PTEX.PageNumber} \NC\NR +\NC \tt 8 \NC \type{PTEX.InfoDict} \NC\NR \HL \stoptabulate \stopbuffer \placetable - [here][flags] - {The meaning of flags in the font descriptor.} + [here][suppressptexinfo] + {\type{\pdfsuppressptexinfo} bit meanings.} {\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. +Thus, the value \type{-1}, or the sum of all defined bits, will suppress +everything. -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. +\type{PTEX.Fullbanner} is included by default in the general document +info dictionary, as mentioned under \type{\pdfinfo} above. The other +\type{PTEX.*} keys are included when a \PDF\ is included in the document +(and not otherwise), as described in \in{section}[sec.addpdfkeys]. -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. +This conditional suppression can be useful in making reproducible +\PDF{}s. \introduced{1.40.17} -\stopnarrower +\pdftexprimitive{\Syntax{\Tex{\pdfcatalog} \Something{general text} + \Optional{\Literal{openaction} \Something{action spec}}}} +\bookmark{\tex{pdfcatalog}} -If the {\em fontflags} field is not given, and the font is embedded, -\PDFTEX\ treats it as the value~4 (decimal, that is, bit position 3 is set), -a symbolic font. For non-embedded fonts, the default value is -\type{0x22}, a non-symbolic serif font. If you do not know the correct -value, it is best not to specify it at all, as specifying a bad value of -font flags may cause trouble in viewers. On the other hand this option -is not absolutely useless because it provides backward compatibility -with older map files (see the {\em fontfile} description below). +Similar to the document info section is the document catalog, where +possible keys are \type{/URI}, which specifies the base \URL\ of the +document, and \type {/PageMode}, which determines how the \PDF\ viewer +displays the document on startup. The possibilities for the latter are +explained in \in {table} [pagemode]: -\stopdescription +\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 -\startdescription {special} -specifies font manipulations in the same way as -\type{dvips}. Currently only the keywords \type{SlantFont} -and \type{ExtendFont} are interpreted, other instructions (notably -\type{ReEncodeFont} and its parameters, see {\em encoding} below) are -just ignored. The permitted \type{SlantFont} range is $-$1..1; -for \type{ExtendFont} it's $-$2..2. The block of {\em special} -instruction must be enclosed by double quote characters: \type{"}. +\placetable + [here][pagemode] + {Supported \type{/PageMode} values.} + {\getbuffer} -\stopdescription +The default \type{/PageMode} setting is \type{/UseNone}. In +full||screen mode, there is no menu bar, window controls, nor any other +window present. -\startdescription {encodingfile} specifies the name of the file -containing the external encoding vector to be used for the font. The -encoding file name must have the extension \type{.enc}, and the file -name including extension must be given with either a preceding~\type{<} -character or a preceding~\type{<[}. The format of the encoding vector is -identical to that used by \type{dvips}. If no encoding is specified, the -font's built||in default encoding is used. The {\em encodingfile} field -may be omitted if you are sure that the font resource has the correct -built||in encoding. In general this option is highly recommended, and it -is {\em required} when subsetting a TrueType font. +After the \Something{general text}, a construct \Literal{openaction} +\Something{action spec} can be given, where \Literal{openaction} is a +\PDFTEX\ keyword, and \Something{action spec} specifies the action to be +taken when opening the document. This \Something{action spec} is the +same as for internal links; see \in {section} [linking]. (Instead of +using this method, one can also write the open action directly into the +catalog.) -Starting with version 1.40.19, an encoding file can also be specified -for bitmap \PK\ fonts. In this case, it assigns the glyph names from the -given encoding vector, which can be used with the -\type{\pdfglyphtounicode} primitive (q.v.). For example: +Several settings can be made in one \type{\pdfcatalog} call, for +example: \starttyping -\pdfglyphtounicode{ffi}{0066 0066 0069} % normally: \input glyphtounicode -\pdfgentounicode=1 -\pdfmapline{cmb10 <7t.enc} -\font\cmb=cmb10 \cmb ffi +\pdfcatalog{ + /PageMode /FullScreen +} openaction goto page 2 {/Fit} \stoptyping -The result is a \PDF\ file with a correctly-labeled \type{/ffi} -character instead of the numeric character position in the -\type{cmb10.tfm} (decimal 14). - -\stopdescription - -\startdescription {fontfile} -sets the name of the font file to be embedded into the \PDF\ output for a -given \TeX\ font (the {\em tfmname}~$\leftrightarrow$~{\em fontfile} -mapping is the most prominent use of the \filename{pdftex.map} file). -The font file name must belong to a Type~1 or TrueType font file. If -the {\em fontfile} field is missing, no font embedding can take place; -in case the {\em psname} field does not contain one of the 14 standard -font names also a warning will be given. Not embedding a font into a \PDF\ -file might be troublesome, as it requires that the font or some similar -looking replacement font is available within the \PDF\ viewer, so that -it can render the glyphs with its own font version. +\pdftexprimitive{\Syntax{\Tex{\pdfcreationdate} \Whatever{expandable}}} +\bookmark{\tex{pdfcreationdate}} -The font file name should be preceded by one or two special characters, -specifying how to handle the font file: +Expands to the date string \PDFTEX\ uses in the info dictionary of the +document, \eg\ for this file {\tt\pdfcreationdate}. \introduced{1.30.0} -\startitemize -\item If the font file name is preceded by a \type{<} character, the - font file will be only partially embedded in the \PDF\ output - (``subsetted''), meaning that only used glyphs are written to - the \PDF\ file. This is the most common use and is {\em strongly - recommended} for any font, as it ensures the portability and - reduces the size of the \PDF\ output. Subsetted fonts are included - in such a way that name and cache clashes are minimized. +\pdftexprimitive{\Syntax{\Tex{\pdfnames} \Something{general text}}} +\bookmark{\tex{pdfnames}} -\item If the font file name is preceded by a double \type{<<}, the font - file will be included entirely --- all glyphs of the font are - embedded, including even those not used in the document. Apart - from causing large size \PDF\ output, this option may cause - troubles with TrueType fonts, so it is normally not recommended - for Type~1 or TrueType fonts. But this is currently the only mode - that allows the use of OpenType fonts. This mode might also be - useful in case the font is atypical and cannot be subsetted well - by \PDFTEX. {\em Beware: proprietary font vendors typically - forbid full font inclusion.} +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. -\item If no special character precedes the font file name, it is - ignored, with a warning (this case was deprecated in \PDFTEX\ - version 1.40.0). You achieve exactly the same \PDF\ result if you - just remove the font file name from the map entry. Then the glyph - widths that go into the \PDF~file are extracted from the - \TFM~file, and a font descriptor object is created that contains - approximations of the font metrics for the selected font. +\pdftexprimitive{\Syntax{\Tex{\pdftrailer} \Something{general text}}} +\bookmark{\tex{pdftrailer}} -\item Specifying the {\em psname} and no font file name is only useful - as a last-ditch fallback when you do not want to embed the font - (\eg\ due to font license restrictions), but wish to use the font - metrics and let the \PDF\ viewer generate instances that look - close to the used font in case the font resource is not installed - on the system where the \PDF\ output will be viewed or - printed. To use this feature, the font flags {\em must} be - specified, and it must have the bit~6 set on, which means that - only fonts with the Adobe Standard Roman Character Set can be - simulated. The only exception is the case of a symbolic font, - which is not very useful. +This command puts its argument text verbatim into the file trailer +dictionary. Example: \type{\pdftrailer {/mytrlrkey /mytrlrval}}. +\introduced{1.11a} -\stopitemize +\pdftexprimitive{\Syntax{\Tex{\pdftrailerid} \Something{general text}}} +\bookmark{\tex{pdftrailerid}} -If you encounter problematic lookups, for instance if \PDFTEX\ tries -to open a \type{.pfa} file instead of a \type{.pfb}, you can add -the suffix to the filename. In this respect, \PDFTEX\ completely relies -on the \type{kpathsea} library. +Use the \Something{general text} to seed the \type{/ID} value in the +trailer, instead of the default combination of the input file +name and starting time. If the argument is empty, the \type{/ID} is +omitted entirely. Example: \type{\pdftrailerid{}}. This can be useful +in making reproducible \PDF{}s. \introduced{1.40.17} -\stopdescription +%*********************************************************************** -For Type~1 and TrueType fonts, the font file will be included only once -in the \PDF\ output, regardless of how many \TeX\ \type{\font} instances -are used in the document. For instance, given +\subsection{Fonts} -\starttyping -\font\a = cmr12 -\font\b = cmr12 at 11pt -\stoptyping +\pdftexprimitive{\Syntax{\Tex{\pdfpkresolution} \Whatever{integer}}} +\bookmark{\tex{pdfpkresolution}} -the outline file \type{cmr12.pfb} will only be included once in the -\PDF, and merely scaled down to create the instance for \type{\b}. +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. -If a used font is not present in the map files, \PDFTEX\ will try to use -\PK~fonts as most \DVI\ drivers do, creating \PK~fonts on||the||fly if -needed. This is the normal, and recommended, way to use bitmap fonts. +\pdftexprimitive{\Syntax{\Tex{\pdffontexpand} + \Something{font} \Something{stretch} \Something{shrink} + \Something{step} \Optional{\Literal{autoexpand}}}} +\bookmark{\tex{pdffontexpand}} -To summarize this rather confusing story, we include some example map -lines. The most common way is to embed only a subset of glyphs from a -font for a particular desired encoding, like this: +This extension to \TEX's font definitions controls a major \PDFTEX\ feature +called {\em font expansion}. We describe this by an example: \starttyping -ptmri8r Times-Italic <8r.enc -o -\stoptyping +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. -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}. +\pdftexprimitive{\Syntax{\Tex{\rpcode} \Something{font} + \Something{8-bit number} \Whatever{integer}}} +\bookmark{\tex{rpcode}} -To use a new TrueType font the minimal steps may look like below. We suppose -that \filename {test.map} is used. +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 -ttf2afm -e 8r.enc -o times.afm times.ttf -afm2tfm times.afm -T 8r.enc -echo "times TimesNewRomanPSMT <8r.enc >test.map +\rpcode\somefont`,=200 +\rpcode\somefont`-=150 \stoptyping -There are a few limitations with TrueType fonts in comparison with -Type~1 fonts: - -\startitemize[a,packed] -\item The special effects SlantFont|/|ExtendFont did not work - before version 1.40.0. -\item To subset a TrueType font, the font must be specified as re||encoded, - therefore an encoding vector must be given. -\item TrueType fonts coming with embedded \PDF\ files are kept - untouched; they are not replaced by local ones. -\stopitemize - -For much more about \PDFTEX\ and TrueType fonts, including many details -on handling glyph names, see ``A closer look at TrueType fonts and -\PDFTEX'', {\em TUGboat} 30:1 (2009), pp.~32||34, \from[thanh_truetype_tub] - -%*********************************************************************** - -\section{Formal syntax specification} - -This section formally specifies the \PDFTEX-specific extensions to the -\TEX\ macro programming language. Most primitives are prefixed by -\type{pdf}. The general definitions and syntax rules follow after the -list of primitives. - -Two new units of measure were introduced in \PDFTEX\ 1.30.0: the -new Didot (1\,nd~=~0.375\,mm) and the new Cicero (1\,nc~=~12\,nd) -(the former was proposed by \ISO\ in 1975). - -% Generated list of primitives (see Makefile). -\input pdftex-syntax.tex - -\subsubject{General definitions and syntax rules} - -\startpacked - -%%S NL -%%S Syntax rules: - -\Syntax{ -\Something{general text} \Means % - \Lbrace \Something{balanced text} \Rbrace -} - -\Syntax{ -\Something{attr spec} \Means % - \Literal{attr} \Something{general text} -} +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). -\Syntax{ -\Something{resources spec} \Means % - \Literal{resources} \Something{general text} -} +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. -\Syntax{ -\Something{rule spec} \Means % - (\Literal{width} \Or \Literal{height} \Or \Literal{depth}) % - \Something{dimen} \Optional{\Something{rule spec}} -} +Changes to this table are global, i.e., ignore \TeX's usual grouping, +and apply only to the given \Something{font}. -%\Syntax{\Something{object type spec} \Means -% \Optional{\Literal{stream} -% \Optional{\Something{attr spec}}} \Something{object contents}} +\pdftexprimitive{\Syntax{\Tex{\lpcode} \Something{font} + \Something{8-bit number} \Whatever{integer}}} +\bookmark{\tex{lpcode}} -\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} -} +This is similar to \type{\rpcode}, but affects the amount by which +characters may protrude into the left margin. Here also the given integer +value is clipped to the range $-1000..1000$. -\Syntax{ -\Something{annot type spec} \Means % - \Literal{reserveobjnum} - \Or \Next % - \Optional{\Literal{useobjnum} \Something{number}} % - \Optional{\Something{rule spec}} % - \Something{general text} -} +Changes to this table are global, i.e., ignore \TeX's usual grouping, +and apply only to the given \Something{font}. -\Syntax{ -\Something{object contents} \Means % - \Something{file spec} - \Or \Something{general text} -} +\pdftexprimitive{\Syntax{\Tex{\leftmarginkern} \Something{box number} + \Whatever{expandable}}} +\bookmark{\tex{leftmarginkern}} -\Syntax{ -\Something{xform attr spec} \Means % - \Optional{\Something{attr spec}} \Optional{\Something{resources spec}} -} +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} -\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}} -} +These are auxiliary primitives to make character protrusion +more versatile. When using the \TEX\ primitive \type{\unhbox} or +\type{\unhcopy}, the margin kerns at either end of the unpackaged +hbox will be removed (\eg\ to avoid weird effects if several +hboxes are unpackaged behind each other into the same horizontal +list). These \type{\unhbox} or \type{\unhcopy} are often used together +with \type{\vsplit} for dis- and re||assembling of paragraphs, \eg\ to +add line numbers. Paragraphs treated like this do not show character +protrusion by default, as the margin kerns have been removed during the +unpacking process. -\Syntax{ -\Something{outline spec} \Means % - \Optional{\Something{attr spec}} % - \Something{action spec} % - \Optional{\Literal{count} \Something{number}} % - \Something{general text} -} +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). -\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} -} +\starttyping +\dimen0=\leftmarginkern\testline +\dimen1=\rightmarginkern\testline +\hbox to\hsize{\kern\dimen0\unhcopy\testline\kern\dimen1} +\stoptyping -\Syntax{ -\Something{user-action spec} \Means % - \Something{general text} -} +\pdftexprimitive{\Syntax{\Tex{\rightmarginkern} \Something{box number} + \Whatever{expandable}}} +\bookmark{\tex{rightmarginkern}} -%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} -} +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} -\Syntax{ -\Something{thread-action spec} \Means % - \Optional{\Something{file spec}} \Something{numid} - \Or \Optional{\Something{file spec}} \Something{nameid} -} +\pdftexprimitive{\Syntax{\Tex{\letterspacefont} \Something{control sequence} + \Something{font} \Something{integer}}} +\bookmark{\tex{letterspacefont}} -\Syntax{ -\Something{colorspace spec} \Means % - \Literal{colorspace} \Something{number} -} +This primitive creates an instance of \Something{font} with the widths +of all glyphs increased by \Something{integer} thousandths of an em (as +set in \Something{font}). The effect is letter spacing, but the glyphs +are actually larger (sidebearings are increased), so a single glyph will +take more space. For instance, the following creates a font +\type{\lsfont} whose glyphs are all 1.2\,pt larger than those of +\type{\normalfont}: -\Syntax{ -\Something{pdf box spec} \Means % - \Literal{mediabox} % - \Or \Literal{cropbox} % - \Or \Literal{bleedbox} % - \Or \Literal{trimbox} % - \Or \Literal{artbox} -} +\starttyping +\font\normalfont=myfont at 12pt +\letterspacefont\lsfont\normalfont 100 +\stoptyping -\Syntax{ -\Something{map spec} \Means % - \Lbrace \Optional{\Something{map modifier}} % - \Something{balanced text} \Rbrace -} +Negative values are allowed for \Something{integer}. +Letter spacing works natively in \PDF\ mode only, unless special fonts are +devised (in our example, a \type{myfont+100ls} font), as with font expansion. -\Syntax{ -\Something{map modifier} \Means % - \Literal{+} \Or \Literal{=} \Or \Literal{-} -} +\pdftexprimitive{\Syntax{\Tex{\pdfcopyfont} \Something{control sequence} + \Something{font}}} +\bookmark{\tex{pdfcopyfont}} -\Syntax{ -\Something{numid} \Means % - \Literal{num} \Something{number} -} +This primitive defines \Something{control sequence} as a synonym for +\Something{font}. -\Syntax{ -\Something{nameid} \Means % - \Literal{name} \Something{general text} -} +\pdftexprimitive{\Syntax{\Tex{\pdffontattr} \Something{font} + \Something{general text}}} +\bookmark{\tex{pdffontattr}} -\Syntax{ -\Something{newwindow spec} \Means % - \Literal{newwindow} \Or \Literal{nonewwindow} -} +This primitive inserts the \Something{general text} to the \type{/Font} +dictionary. The text must conform to the specifications as laid down in +the \PDFReference, otherwise the document can be invalid. For examples, +see the \type{cmap} and \type{CJK} packages. -\Syntax{ -\Something{dest spec} \Means % - \Something{numid} \Something{dest type} - \Or \Something{nameid} \Something{dest type} -} +\pdftexprimitive{\Syntax{\Tex{\pdffontname} \Something{font} + \Whatever{expandable}}} +\bookmark{\tex{pdffontname}} -\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} -} +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}. -\Syntax{ -\Something{thread spec} \Means % - \Optional{\Something{rule spec}} % - \Optional{\Something{attr spec}} % - \Something{id spec} -} +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. -\Syntax{ -\Something{id spec} \Means % - \Something{numid} \Or \Something{nameid} -} +\pdftexprimitive{\Syntax{\Tex{\pdffontobjnum} \Something{font} + \Whatever{expandable}}} +\bookmark{\tex{pdffontobjnum}} -\Syntax{ -\Something{file spec} \Means % - \Literal{file} \Something{general text} -} +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}. -\Syntax{ -\Something{page spec} \Means % - \Literal{page} \Something{number} -} +Use of \type{\pdffontname} and \type{\pdffontobjnum} allows users full +access to all the font resources used in the document. -\Syntax{ -\Something{expand spec} \Means % - \Something{stretch} % - \Something{shrink} % - \Something{step} % - \Optional{\Literal{autoexpand}} -} +\pdftexprimitive{\Syntax{\Tex{\pdffontsize} \Something{font} + \Whatever{expandable}}} +\bookmark{\tex{pdffontsize}} -\Syntax{ -\Something{stretch} \Means % - \Something{number} -} +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}. -\Syntax{ -\Something{shrink} \Means % - \Something{number} -} +\pdftexprimitive{\Syntax{\Tex{\pdfincludechars} \Something{font} + \Something{general text} \Whatever{expandable}}} +\bookmark{\tex{pdfincludechars}} -\Syntax{ -\Something{step} \Means % - \Something{number} -} +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. -\Syntax{ -\Something{pre spec} \Means % - \Literal{pre} -} +\pdftexprimitive{\Syntax{\Tex{\pdfomitcharset} \Whatever{integer}}} +\bookmark{\tex{pdfomitcharset}} -\Syntax{ -\Something{pdfliteral spec} \Means % - \Literal{direct} \Or \Literal{page} -} +If this primitive parameter is zero (the default), the \type{/CharSet} +entry is included as usual for fonts in the \PDF\ output; if it is set +to 1, then \type{/CharSet} is omitted. (Other values may have other +meanings in the future, so do not rely on them.) -\Syntax{ -\Something{pdfspecial spec} \Means % - \Lbrace \Optional{\Something{pdfspecial id} % - \Optional{\Something{pdfspecial modifier}}} % - \Something{balanced text} \Rbrace -} +Explanation: This parameter was created because the \PDFA-1 standard +requires \type{/CharSet}, whereas \PDFA-2 and \PDFA-3 allow it to be +omitted but have extraordinary requirements, which \PDFTEX\ does not +currently meet, if it is included.\introduced{1.40.20} -\Syntax{ -\Something{pdfspecial id} \Means % - \Literal{pdf:} \Or \Literal{PDF:} -} +\pdftexprimitive{\Syntax{\Tex{\pdfuniqueresname} \Whatever{integer}}} +\bookmark{\tex{pdfuniqueresname}} -\Syntax{ -\Something{pdfspecial modifier} \Means % - \Literal{direct:} -} +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. -\Syntax{ -\Something{stack action} \Means % - \Literal{set} \Or \Literal{push} \Or \Literal{pop} \Or \Literal{current} -} +\pdftexprimitive{\Syntax{\Tex{\pdfmapfile} \Something{map spec}}} +\bookmark{\tex{pdfmapfile}} -\stoppacked +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. -A \Something{general text} is expanded immediately, like \type{\special} -in traditional \TEX, unless explicitly mentioned otherwise. +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. +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: -Some of the object and image related primitives can be prefixed by -\type{\immediate}. More about that in the next sections. +\starttyping +\pdfmapfile{+myfont.map} +\pdfmapline{+ptmri8r Times-Italic <8r.enc