diff options
Diffstat (limited to 'Master/texmf-dist/doc/pdftex')
| -rw-r--r-- | Master/texmf-dist/doc/pdftex/manual/ChangeLog | 43 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/pdftex/manual/Makefile | 7 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/pdftex/manual/pdftex-a.pdf | bin | 948745 -> 1002639 bytes | |||
| -rw-r--r-- | Master/texmf-dist/doc/pdftex/manual/pdftex-syntax.txt | 23 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/pdftex/manual/pdftex-t.tex | 1601 |
5 files changed, 971 insertions, 703 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 <karl@freefriends.org> + + * pdftex-t.tex (ptex_devel): svn://tug.org url. + +2021-11-06 Marcel Kr\"uger <tex@2krueger.de> + + * pdftex-t.tex (\showstream): document. + +2021-11-06 Marcel Kr\"uger <tex@2krueger.de> + + * pdftex-t.tex: missed bookmarks for \pdfgentounicode and + a few other primitives. + +2021-11-04 Karl Berry <karl@freefriends.org> + + * 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 <tex@2krueger.de> + + * pdftex-t.tex: document structured destinations (\pdfdest struct NNN). + Also bump document font size to 11pt. + +2021-09-25 Karl Berry <karl@freefriends.org> + + * pdftex-t.tex (\pdfstartlink): organize into lists. + +2021-07-25 Karl Berry <karl@freefriends.org> + + * pdftex-t.tex: oops, \partokencontext sorts before \partokenname. + * pdftex-t.tex (\partokenname, \partokencontext): document these + new primitives. + +2021-07-24 Karl Berry <karl@freefriends.org> + + * 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 <karl@freefriends.org> * 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 Binary files differindex f5d6372f936..4fa8985b52d 100644 --- a/Master/texmf-dist/doc/pdftex/manual/pdftex-a.pdf +++ b/Master/texmf-dist/doc/pdftex/manual/pdftex-a.pdf 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 <font> <8-bit number> (integer) \shbscode <font> <8-bit number> (integer) +\showstream (integer) \stbscode <font> <8-bit number> (integer) \tagcode <font> <8-bit number> (integer) \tracinglostchars (integer) @@ -123,6 +124,7 @@ %% General commands: \letterspacefont <control sequence> <font> <integer> +\partokenname <control sequence> \pdfannot <annot type spec> (h, v, m) \pdfcatalog <general text> [openaction <action spec>] \pdfcolorstack <stack number> <stack action> <general text> @@ -188,11 +190,12 @@ | goto <goto-action spec> | thread <thread-action spec> <user-action spec> --> <general text> -<goto-action spec> --> <numid> - | [<file spec>] <nameid> - | [<file spec>] [<page spec>] <general text> - | <file spec> <nameid> <newwindow spec> - | <file spec> [<page spec>] <general text> <newwindow spec> +<goto-action struct spec> --> struct (<numid> | nameid | <general text>) +<goto-action spec> --> [<goto-action struct spec>] <numid> + | [<file spec>] [<goto-action struct spec>] <nameid> + | [<file spec>] [<goto-action struct spec>] [<page spec>] <general text> + | <file spec> [<goto-action struct spec>] <nameid> <newwindow spec> + | <file spec> [<goto-action struct spec>] [<page spec>] <general text> <newwindow spec> <thread-action spec> --> [<file spec>] <numid> | [<file spec>] <nameid> <colorspace spec> --> colorspace <number> @@ -202,8 +205,9 @@ <numid> --> num <number> <nameid> --> name <general text> <newwindow spec> --> newwindow | nonewwindow -<dest spec> --> <numid> <dest type> - | <nameid> <dest type> +<dest spec> --> [struct <number>] \\ + (<numid> | <nameid>) + <dest type> <dest type> --> xyz [zoom <number>] | fitr <rule spec> | fitbh @@ -226,3 +230,8 @@ <pdfspecial id> --> pdf: | PDF: <pdfspecial modifier> --> direct: <stack action> --> set | push | pop | current +<goto-action spec> --> [<goto-action struct spec>] <numid> + | [<file spec>] [<goto-action struct spec>] <nameid> + | [<file spec>] [<goto-action struct spec>] [<page spec>] <general text> + | <file spec> [<goto-action struct spec>] <nameid> <newwindow spec> + | <file spec> [<goto-action struct spec>] [<page spec>] <general text> <newwindow spec> 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,496 +823,6 @@ We now turn to specifics of \PDFTEX. %*********************************************************************** -\section{Getting started} - -This section describes the steps needed to get \PDFTEX\ running on -a system where \PDFTEX\ is not yet installed. Nowadays virtually all -\TEX\ distributions have \PDFTEX\ as a component, such as \TEXLIVE, -\MIKTEX, \PROTEXT, and \MACTEX. The ready to run -\TEXLIVE\ distribution comes with \PDFTEX\ versions for many \UNIX, -\WIN, and \MACOSX\ systems; more information can be found at -\hbox{\from[texlive].} There are also \WIN-specific distributions which -contain \PDFTEX, under \from[win32]: \MIKTEX\ by Christian Schenk, and -\PROTEXT\ (based on \MIKTEX) by Thomas Feuerstack. When you use any -of these distributions, you don't need to bother with the \PDFTEX\ -installation procedure in the next sections. - -If there is no precompiled \PDFTEX\ binary for your system, or the version -coming with a distribution is not the current one and you would like to -try out a fresh \PDFTEX\ immediately, you will need to build \PDFTEX\ -from sources; read on. You should already have a working \TEX\ system, -\eg\ \TEXLIVE, into which the freshly compiled \PDFTEX\ will -be integrated. Note that the installation description in this manual -is \WEBC||specific. - -%*********************************************************************** - -\subsection{Getting sources and binaries} - -The latest sources of \PDFTEX\ are distributed for compilation on \UNIX\ -systems (including \GNU/Linux), and \WIN\ systems. The primary home -page is \from[ptex_org], where you also find bug tracking information. -Development sources are at \from[ptex_devel]. Precompiled \PDFTEX\ -binaries for various systems might be available in subdirectories below -\from[ctan_systems], or via \TEX\ distribution web pages. - -%*********************************************************************** - -\subsection{Compiling} - -The compilation is expected to be easy on \UNIX||like systems and -can be described best by example. Assuming that the file \filename -{pdftex.zip} is downloaded to some working directory, \eg\ -\filename {\$HOME/pdftex}, on a \UNIX\ system the following steps are -needed to compile \PDFTEX: - -\startesctyping -cd pdftex.../source -./build-pdftex.sh -\stopesctyping - -The binary \filename{pdftex} is then built in the subdirectory -\filename{build/texk/web2c}. - -The obsolescent binary \filename{pdfetex} is still generated for backward -compatibility, but since version 1.40 it is just a symbolic link to or copy -of the file \filename{pdftex}. - -As well as the main \filename{pdftex} binary, binaries for the utilities -\filename{pdftosrc} and \filename{ttf2afm} are generated. - -Incidentally, for \PDFTEX\ maintains, a sibling script to -\type{build-pdftex.sh} is included, namely \type{sync-pdftex.sh}, which -syncs changes from a \TEXLIVE\ source repository to a \PDFTEX\ source -repository. Read the script before using it. And don't use it unless -you understand what you read. - -%*********************************************************************** - -\subsection{Placing files} - -The next step is to put the freshly compiled \filename{pdftex}, -\filename{pdftosrc}, and \filename{ttf2afm} binaries into the binary -directory (\eg\ for a typical \TEXLIVE\ system, and on the appropriate -platform) \filename{/usr/local/texlive/\rcsyear/bin/x86_64-linux}. - -If you're doing this into a live hierarchy, don't forget to do a -\type{texconfig-sys init} afterwards, so that all formats are -regenerated system-wide with the fresh \filename{pdftex} binary. - -%*********************************************************************** - -\subsection{Setting search paths} - -\WEBC||based programs, including \PDFTEX, use the \WEBC\ run||time -configuration file called \filename {texmf.cnf}. The location -of this file is the appropriate position within the \TDS\ tree -relative to the place of the \PDFTEX\ binary; on a \TEXLIVE\ system, -\filename{texmf.cnf} is typically located either in the directory -\filename{texmf-dist/web2c}. The path to -file \filename{texmf.cnf} can also be set up by the environment variable -\type{TEXMFCNF}. - -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. - -\PDFTEX\ uses the search path variables shown in -\in{table}[tbl:spathvar], among others. - -\startbuffer -\starttabulate[|l|l|] -\HL -\NC \bf used for \NC \bf texmf.cnf \NC\NR -\HL -\NC output files \NC \type{TEXMFOUTPUT} \NC\NR -\NC input files, images \NC \type{TEXINPUTS} \NC\NR -\NC format files \NC \type{TEXFORMATS} \NC\NR -\NC \TeX\ pool files \NC \type{TEXPOOL} \NC\NR -\NC encoding files \NC \type{ENCFONTS} \NC\NR -\NC font map files \NC \type{TEXFONTMAPS} \NC\NR -\NC \TFM\ files \NC \type{TFMFONTS} \NC\NR -\NC virtual fonts \NC \type{VFFONTS} \NC\NR -\NC Type~1 fonts \NC \type{T1FONTS} \NC\NR -\NC TrueType fonts \NC \type{TTFONTS} \NC\NR -\NC OpenType fonts \NC \type{OPENTYPEFONTS} \NC\NR -\NC bitmap fonts \NC \type{PKFONTS} \NC\NR -\HL -\stoptabulate -\stopbuffer - -\placetable[here][tbl:spathvar] - {The principal \WEBC\ variables.} - {\getbuffer} - -\PathDescription {TEXMFOUTPUT} Normally, \PDFTEX\ puts its output files -in the current directory, overridden by the \type{-output-directory} -option. If any output file cannot be opened there, it tries to open it -in the environment variable \type{TEXMFOUTPUT}, if that is set. There is -no default value for that variable. For example, if \type{TEXMFOUTPUT} -has the value \type{/tmp}, and you run \type{pdftex paper} when the -current directory is not writable, \PDFTEX\ attempts to create -\type{/tmp/paper.log} (and \type{/tmp/paper.pdf}, etc.) - -\PathDescription {TEXINPUTS} This variable specifies where \PDFTEX\ finds -its input files. Image files are considered -input files and searched for along this path. - -\PathDescription {TEXFORMATS} Search path for format (\type{.fmt}) files. - -\PathDescription {TEXPOOL} Search path for pool (\type{.pool}) files; no -longer used, since the pool file (program strings) are compiled into -the binary. - -\PathDescription {ENCFONTS} Search path for encoding (\type{.enc}) files. - -\PathDescription {TEXFONTMAPS} Search path for font map (\type{.map}) files. - -\PathDescription {TFMFONTS} Search path for font metric (\type{.tfm}) files. - -\PathDescription {VFFONTS} Search path for virtual font (\type{.vf}) -files. Virtual fonts are fonts made up of other fonts. -Because \PDFTEX\ produces the -final output code, it must consult those files. - -\PathDescription {T1FONTS} Search path for Type~1 font files (\type{.pfa} -and \type{.pfb}). These outline (vector) fonts are to be preferred over -bitmap \PK\ fonts. In most cases Type~1 fonts are used and this variable -tells \PDFTEX\ where to find them. - -\PathDescription {TTFONTS,\hfil\break \hbox{OPENTYPEFONTS}} Search paths -for TrueType (\type{.ttf}) and OpenType (\type{.otf}) font files. Like -Type~1 fonts, TrueType and OpenType fonts are also outlines. - -\PathDescription {PKFONTS} Search path for packed (bitmap) font -(\type{.pk}) files. -Unfortunately bitmap fonts are still displayed poorly by some \PDF\ -viewers, so when possible one should use outline fonts. When no outline -is available, \PDFTEX\ tries to locate a suitable \PK\ font (or invoke -a process that generates it). - -\PathDescription{TEXFONTS} Fallback for all the font paths, so that if -you want to look in a particular directory for fonts on a given run, you -can set that one variable. - -Many more variables may be consulted, and there are many details to -file name lookups. See the Kpathsea manual (\from [kpathsea]). - -%*********************************************************************** - -\subsection[cfg]{The \PDFTEX\ configuration} - -We must keep in mind that, as opposed to \TEX\ with its \DVI\ output, -the \PDFTEX\ program does not have a separate postprocessing stage to -transform the \TEX\ input into final \PDF. As a consequence, all data -needed for building a ready \PDF\ page must be available during the -\PDFTEX\ run, in particular information on media dimensions and offsets, -graphics files for embedding, and font information (font files, -encodings). - -When \TEX\ builds a page, it places items relative to the (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. - -In \PDF, the paper dimensions are part of the page definition, and -\PDFTEX\ therefore requires that they be defined at the beginning of -the \PDFTEX\ run. As with pages described by \POSTSCRIPT, the \PDF\ -reference point is in the lower||left corner. - -Formerly, these dimensions and other \PDFTEX\ parameters were read -in from a configuration file named \filename{pdftex.cfg}, which had -a special (non-\TEX) format, at the start of processing. Nowadays such -a file is ignored by \PDFTEX. Instead, the page dimensions and offsets, -as well as many other parameters, can be set by \PDFTEX\ primitives -during the \PDFTEX\ format building process, so that the settings are -dumped into the fresh format and consequently will be used when \PDFTEX\ -is later called with that format. All settings from the format can -still be overridden during a \PDFTEX\ run by using the same primitives. -This new configuration concept is a more unified approach, as it avoids -the configuration file with a special format. - -A list of \PDFTEX\ primitives relevant to setting up the \PDFTEX\ engine -is given in \in{table}[tbl:configparms]. All primitives are described in -detail within later sections. \in{Figure}[in:pdftexconfig] shows a recent -configuration file (\type{pdftexconfig.tex}) in \TEX\ format, using the -primitives from \in{table}[tbl:configparms], which typically is read -in during the format building process. It enables \PDF\ output, sets paper -dimensions and the default pixel density for \PK\ font inclusion. The default -values are chosen so that \PDFTEX\ often can be used (\eg\ in \type{-ini} mode) -even without setting any parameters. - -\startbuffer -\starttabulate[|l|l|l|l|l|] -\HL -\NC \bf internal name \NC \bf type \NC\bf default\NC\bf comment\NC\NR -\HL -\NC \type{\pdfoutput} \NC integer \NC 0 \NC \DVI \NC\NR -\NC \type{\pdfadjustspacing} \NC integer \NC 0 \NC off \NC\NR -\NC \type{\pdfcompresslevel} \NC integer \NC 9 \NC best \NC\NR -\NC \type{\pdfobjcompresslevel} \NC integer \NC 0 \NC no object streams \NC\NR -\NC \type{\pdfdecimaldigits} \NC integer \NC 4 \NC max. \NC\NR -\NC \type{\pdfimageresolution} \NC integer \NC 72 \NC dpi \NC\NR -\NC \type{\pdfpkresolution} \NC integer \NC 0 \NC 72\,dpi \NC\NR -\NC \type{\pdfpkmode} \NC token reg.\NC empty \NC mode set in \type{mktex.cnf} \NC\NR -\NC \type{\pdfuniqueresname} \NC integer \NC 0 \NC \NC\NR -\NC \type{\pdfprotrudechars} \NC integer \NC 0 \NC \NC\NR -\NC \type{\pdfgentounicode} \NC integer \NC 0 \NC \NC\NR -\NC \type{\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 -\HL -\stoptabulate -\stopbuffer - -\placetable[here][tbl:configparms] - {The set of \PDFTEX\ configuration parameters.} - {\getbuffer} - -\startbuffer -\tx\setupinterlinespace -\startframedtext -\starttyping -% tex-ini-files 2016-04-15: pdftexconfig.tex - -% Load shared (PDF) settings in pdfTeX - -% Enable PDF output -\pdfoutput = 1 - -% Paper size: dimensions given in absolute terms -\pdfpageheight = 11 true in -\pdfpagewidth = 8.5 true in - -% Enable PDF 1.5 output and thus more compression -\pdfminorversion = 5 -\pdfobjcompresslevel = 2 - -% Low-level settings unlikely ever to need to change -\pdfcompresslevel = 9 -\pdfdecimaldigits = 3 -\pdfpkresolution = 600 -\pdfhorigin = 1 true in -\pdfvorigin = 1 true in -\stoptyping -\stopframedtext -\stopbuffer - -\placefigure[here][in:pdftexconfig] - {\PDFTEX\ configuration file for \TEXLIVE\ (\filename{pdftexconfig.tex}).} - {\getbuffer} - -Independent of whether such a configuration file is read or not, the -first action in a \PDFTEX\ run is that the program reads the global -\WEBC\ configuration file (\filename{texmf.cnf}), which is common to all -programs in the \WEBC\ system. This file mainly defines file search -paths, the memory layout (\eg\ string pool and hash size), and a few -other general parameters. - -%*********************************************************************** - -\subsection{Creating format files} - -\startbuffer -\tx\setupinterlinespace -\startframedtext -\starttyping -% Thomas Esser, 1998. public domain. -\input etex.src -\dump -\endinput -\stoptyping -\stopframedtext -\stopbuffer - -\placefigure[here][in:etexini] - {File \type{etex.ini} for the plain \ETEX\ format with \DVI\ output.} - {\getbuffer} - -\startbuffer -\tx\setupinterlinespace -\startframedtext -\starttyping -% Thomas Esser, 1998. public domain. -% This is used for pdftex and pdfetex, which are now identical: both -% with e-TeX extensions, both with pdf output. -\input pdftexconfig.tex -\input etex.src -\input pdftexmagfix.tex -\dump -\endinput -\stoptyping -\stopframedtext -\stopbuffer - -\placefigure[here][in:pdfetexini] - {File \type{pdfetex.ini} for plain \ETEX\ with \PDF\ output.} - {\getbuffer} - -\startbuffer -\tx\setupinterlinespace -\startframedtext -\starttyping -% Thomas Esser, 1998. public domain. -\input pdftexconfig.tex -\scrollmode -\input latex.ltx -\endinput -\stoptyping -\stopframedtext -\stopbuffer - -\placefigure[here][in:pdflatexini] - {File \type{pdflatex.ini} for the \LATEX\ format with \PDF\ output.} - {\getbuffer} - -The \PDFTEX\ engine supports building formats for \DVI\ and \PDF\ output -in the same way as the classical \TEX\ engine does for \DVI. Format -generation (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. - -It is customary to package the configuration and macro file input -into a \type{.ini} file. \Eg, the file \type{etex.ini} in -\in{figure}[in:etexini] is for generating an \ETEX\ format with \DVI\ -output. It has been traditional for many years to generate -\type{etex.fmt} with \PDFTEX\ rather than the original \ETEX, because -\PDFTEX\ contains a few additional programming and other -non-\PDF-related features on which people have come to rely. - -The \type{pdfetex.ini} file \in{figure}[in:etexini] shows the -corresponding format with \PDF\ output by default; this is what creates -the format file read when \type{pdftex} is normally invoked. - -Finally, \type{pdflatex.ini} \in{figure}[in:pdflatexini] shows how the -\LATEX\ format with \PDF\ output by default is generated. - -The corresponding \PDFTEX\ calls for format generation are: - -\starttyping -pdftex -ini *etex.ini -pdftex -ini *pdfetex.ini -pdftex -ini *pdflatex.ini -\stoptyping - -These calls produce format files \filename{etex.fmt}, -\filename{pdfetex.fmt}, and \filename{pdflatex.fmt}, as the default -format file name is taken from the input file name. You can 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. - -\subsection{Testing the installation} - -When everything is set up, you can test the installation. A simple test -of plain \PDFTEX\ is: - -\starttyping -pdftex story \\end -\stoptyping - -This should typeset the famous one-page short story by A.U. Thor. - -A more thorough and descriptive test is the plain \TEX\ test file -\filename{samplepdf.tex}, available in the distribution in the -\type{samplepdftex/} directory. Process this file by typing: - -\starttyping -pdftex samplepdf -\stoptyping - -If the installation is ok, this should produce a file called -\filename{samplepdf.pdf}. The file \filename {samplepdf.tex} is a good -place to look for examples of how to use \PDFTEX's primitives. - -%*********************************************************************** - -\subsection{Common problems} - -The most common problem with installations is that \PDFTEX\ complains -that something cannot be found. In such cases make sure that -\type{TEXMFCNF} is set correctly, so \PDFTEX\ can find \filename -{texmf.cnf}. The next best place to look|/|edit is the file -\type{texmf.cnf}. When still in deep trouble, set -\type{KPATHSEA_DEBUG=255} before running \PDFTEX\ or use the option -\type{-kpathsea-debug 255}. This will cause \PDFTEX\ to write a lot of -debugging information that can be useful to trace problems. More options -can be found in the \WEBC\ documentation. - -Variables in \filename {texmf.cnf} can be overwritten by environment -variables. Here are some of the most common problems you can encounter when -getting started: - -\startitemize - -\head \type{I can't find the format file `pdftex.fmt'!} \crlf - \type{I can't find the format file `pdflatex.fmt'!} - - The format file is not created (see above how to do that) or - is not properly placed. Make sure that \type{TEXFORMATS} in - \filename {texmf.cnf} contains the path to \filename {pdftex.fmt} - or \filename {pdflatex.fmt}. - -\head \type{Fatal format file error; I'm stymied} - - This appears \eg\ if you forgot to regenerate the \type{.fmt} - files after installing a new version of the \PDFTEX\ binary. - The first line tells by which engine the offending format was generated. - -\head \PDFTEX\ cannot find one or more map files (\type{*.map}), - encoding vectors (\type{*.enc}), virtual fonts, Type~1 fonts, - TrueType or OpenType fonts, or some image file. - - Make sure that the required file exists and the corresponding variable - in \filename {texmf.cnf} contains a path to the file. See above which - variables \PDFTEX\ needs apart from the ones \TEX\ uses. - - When you have installed new fonts, and your \PDF\ viewer complains - about missing fonts, you should take a look at the log file produced - by \PDFTEX. Missing fonts, map files, encoding vectors as well as - missing characters (glyphs) are reported there. - -\stopitemize - -Normally the page content takes one object. This means that one seldom -finds more than a few hundred objects in a simple file. This \PDFTEX\ -manual for instance uses approx.~750 objects. In more complex applications -this number can grow quite rapidly, especially when one uses a lot of -widget annotations, shared annotations or other shared things. In any -case \PDFTEX's internal object table size will automatically grow to the -required size (the parameter \type{obj_tab_size} for manual control of -the object table size is now obsolete and ignored). - -%*********************************************************************** - \section{Invoking \PDFTEX} \PDFTEX\ has many command line options. Except for the simple and @@ -1364,15 +867,14 @@ 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[9pt] % squeeze everything on one page + \switchtobodyfont[10pt] % keep line lengths shorter \stopnotmode \typefile{pdftex-help.txt} -\startnotmode[screen] - \switchtobodyfont[10pt] % squeeze everything on one page -\stopnotmode +\endgroup %*********************************************************************** @@ -1941,14 +1443,19 @@ new Didot (1\,nd~=~0.375\,mm) and the new Cicero (1\,nc~=~12\,nd) \Something{general text} } -%HE Check: +\Syntax{ +\Something{goto-action struct spec} \Means % + \Literal{struct} (\Something{numid} \Or \Literal{nameid} \Or \Something{general text}) +} + +% keep in sync with redundant copy below. \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} + \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{ @@ -1999,8 +1506,9 @@ new Didot (1\,nd~=~0.375\,mm) and the new Cicero (1\,nc~=~12\,nd) \Syntax{ \Something{dest spec} \Means % - \Something{numid} \Something{dest type} - \Or \Something{nameid} \Something{dest type} + \Optional{\Literal{struct} \Something{number}} \\ + (\Something{numid} \Or \Something{nameid}) + \Something{dest type} } \Syntax{ @@ -2328,7 +1836,7 @@ the wished true page height. %*********************************************************************** -\subsection[sec.docinfocatalog]{The document info and catalog} +\subsection[sec.docinfocatalog]{Document info and catalog} \pdftexprimitive{\Syntax{\Tex{\pdfinfo} \Something{general text}}} \bookmark{\tex{pdfinfo}} @@ -2474,6 +1982,13 @@ example: } openaction goto page 2 {/Fit} \stoptyping +\pdftexprimitive{\Syntax{\Tex{\pdfcreationdate} \Whatever{expandable}}} +\bookmark{\tex{pdfcreationdate}} + +Expands to the date string \PDFTEX\ uses in the info dictionary of the +document, \eg\ for this file {\tt\pdfcreationdate}. \introduced{1.30.0} + + \pdftexprimitive{\Syntax{\Tex{\pdfnames} \Something{general text}}} \bookmark{\tex{pdfnames}} @@ -3040,6 +2555,7 @@ value is \type{no_tag}, \type{1} if \type{lig_tag} is set, \type{2} if \type{list_tag} is set or \type{4} (not~3) if \type{ext_tag} is set. \pdftexprimitive{\Syntax{\Tex{\pdfgentounicode} \Whatever{integer}}} +\bookmark{\tex{pdfgentounicode}} By default, \PDFTEX\ does not include a \type{/ToUnicode} resource when including fonts in the output. Such a resource (also called a CMap @@ -3060,6 +2576,7 @@ table using the following command: \pdftexprimitive{\Syntax{\Tex{\pdfglyphtounicode} \Something{general text} \Something{general text}}} +\bookmark{\tex{pdfglyphtounicode}} The first argument is the name of a glyph, the second is a string of Unicode numeric values denoting characters, separated by spaces. For instance: @@ -3092,6 +2609,7 @@ effect. \pdftexprimitive{\Syntax{\Tex{\pdfnobuiltintounicode} \Something{font}}} +\bookmark{\tex{pdfnobuiltintounicode}} The primary purpose of this command is to prevent \PDFTEX\ from generating the \type{ToUnicode}/CMap resource for the given font when @@ -3110,7 +2628,9 @@ Minimal example: \pdftexprimitive{\Syntax{\Tex{\pdfinterwordspaceon}}} +\bookmark{\tex{pdfinterwordspaceon}} \pdftexprimitive{\Syntax{\Tex{\pdfinterwordspaceoff}}} +\bookmark{\tex{pdfinterwordspaceoff}} These commands create corresponding whatsit nodes which turn on/off generation of faked interword spaces in the output. This allows for @@ -3140,6 +2660,7 @@ Back to text with no interword spaces. \introduced{1.40.15} \pdftexprimitive{\Syntax{\Tex{\pdffakespace}}} +\bookmark{\tex{pdffakespace}} Insert a faked interword space to the output, regardless of the value of \type{\pdfinterwordspaceon} and \type{\pdfinterwordspaceoff}. Example: @@ -3318,6 +2839,14 @@ node is searched at shipout time, \PDFTEX\ will write the object \Something{object number} to the \PDF\ output if it has not been written yet. +\pdftexprimitive{\Syntax{\Tex{\pdfretval} \Whatever{read||only integer}}} +\bookmark{\tex{pdfretval}} + +Set to $-1$ if \type{\pdfobj} ignores an invalid object number. Perhaps +this will be used to store the error status of other primitives in the +future. + + %*********************************************************************** \subsection{Page and pages objects} @@ -3828,7 +3357,11 @@ This primitive appends a whatsit node which establishes a destination for links and bookmark outlines; the link is identified by either a number or a symbolic name, and the way the viewer is to display the page must be specified in \Something{dest type}\unkern, which must be -one of those mentioned in \in{table}[appearance]. +one of those mentioned in \in{table}[appearance]. If \Literal{struct} +\Something{number} is used, a structure destination is created instead of a +regular destination, referring to the structure element defined in object +\Something{number}. Structure destinations use a separate namespace and +therefore may have the same identifiers as a regular destination. \startbuffer \starttabulate[|l|l|] @@ -3893,26 +3426,69 @@ is for the sake of speed optimization. The main disadvantage is that these annotations do {\em not} obey transformations issued by \type {\pdfliteral}'s. -The \Something{action spec} specifies the action that should be performed -when the hyperlink is activated while the \Something{user-action spec} -performs a user||defined action. A typical use of the latter is to specify -a \URL, like \typ {/S /URI /URI (https://tug.org/)}, or a named action like -\typ {/S /Named /N /NextPage}. - -A \Something{goto-action spec} performs a GoTo action. Here \Something -{numid} and \Something{nameid} specify the destination identifier (see -below). The \Something{page spec} specifies the page number of the -destination, in this case the zoom factor is given by \Something{general -text}\unkern. A destination can be performed in another \PDF\ file by -specifying \Something{file spec}\unkern, in which case -\Something{newwindow spec} specifies whether the file should be opened -in a new window. A \Something{file spec} can be either a \type{(string)} -or a \type{<<dictionary>>}. The default behavior of the -\Something{newwindow spec} depends on the browser setting. - -A \Something{thread-action spec} performs an article thread reading. The -thread identifier is similar to the destination identifier. A thread can be -performed in another \PDF\ file by specifying a \Something{file spec}\unkern. +The \Something{action spec} specifies the action that should be +performed when the hyperlink is activated, one of (see the syntax +rules) \Literal{user} \Something{user-action spec}, +\Literal{goto} \Something{goto-action spec}, +\Literal{thread} \Something{thread-action spec}. + +\startitemize + +\item A \Something{user-action spec} (\type{user {...}}) performs a +user||defined action. Examples: a \URL, like +\typ {/S /URI /URI (https://tug.org/)}; +or a named action, like \typ {/S /Named /N /NextPage}. + +\item A \Something{goto-action spec} (\type{goto ...}) performs various goto +actions, and is by far the most complex action. Here is a copy of the +syntax, for easier reference: + +\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} +} + +\startitemize + +\item The \Something {numid} and \Something{nameid} alternatives specify a +destination identifier. + +\item The \Something{page spec} alternative specifies a page number for the +destination. In this case, the zoom factor is given by +\Something{general text}\unkern. + +\item The default behavior of the \Something{newwindow +spec} depends on the browser setting. + +\item A destination in another \PDF\ file can be specified with +\Something{file spec}\unkern, in which case \Something{newwindow spec} +specifies whether the file should be opened in a new window. A +\Something{file spec} can be either a \type{(string)} or a +\type{<<}\type{dictionary}\type{>>}. + +\item If a \Something{goto-action spec} contains a +\Something{goto-action struct spec}, then a structure destination is +referenced in addition to the regular destination. The form with +\Something{general text} is used if and only if a \Something{file spec} +is present; then the \Something{general text} should expand to a literal +\PDF\ dictionary describing a structure destination. Otherwise, the +\Something{numid} or \Something{nameid} directly after the +\Literal{struct} keyword identify a destination which must have been +created with \type{\pdfdest} \Literal{struct}\unskip. + +\stopitemize + +\item A \Something{thread-action spec} (\type{thread ...}) performs +article thread reading. The thread identifier, \Something{numid} or +\Something{nameid}, is similar to the destination identifier. A thread +can be performed in another \PDF\ file by specifying a \Something{file +spec}\unkern. + +\stopitemize \pdftexprimitive{\Syntax{\Tex{\pdfendlink} \Modelist{h, m}}} \bookmark{\tex{pdfendlink}} @@ -3951,7 +3527,9 @@ on every run is just noise, and can be suppressed by setting this parameter to a positive number. \introduced{1.40.13} \pdftexprimitive{\Syntax{\Tex{\pdfrunninglinkoff}}} +\bookmark{\tex{pdfrunninglinkoff}} \pdftexprimitive{\Syntax{\Tex{\pdfrunninglinkon}}} +\bookmark{\tex{pdfrunninglinkon}} These commands create corresponding whatsit nodes which turn off/on generation of running links. Their typical usage is to turn off @@ -4380,6 +3958,8 @@ current. \Literal{set} keyword replaces the current value with \Literal{current} keyword instructs just to use the current stack value without modifying the stack at all. \introduced{1.40.0} +%*********************************************************************** + \subsection{Transformations} Since the content of \Tex{\pdfliteral} is not interpreted anyhow, any @@ -4419,7 +3999,9 @@ and end at the same group level. \introduced{1.40.0} %*********************************************************************** -\subsection{Miscellaneous} +\subsection{Macro programming} + +Expansion-related. \pdftexprimitive{\Syntax{\tex {expanded} \Something{tokens} \Whatever{expandable}}} @@ -4430,6 +4012,7 @@ In contrast to \type{\edef}, macro parameter characters do not need to be doubled. \type{\protected} macros are not expanded. \introduced{1.40.20} + \pdftexprimitive{\Syntax{\tex {ifincsname} \Whatever{expandable}}} \bookmark{\tex{ifincsname}} @@ -4447,25 +4030,137 @@ any other case (redefined, made \type{\undefined}, has never been primitive) false is returned. \introduced{1.40.0} -\pdftexprimitive{\Syntax{\Tex{\pdfcreationdate} \Whatever{expandable}}} -\bookmark{\tex{pdfcreationdate}} +flapping\pdftexprimitive{\Syntax{\tex{partokencontext} \Something{number}}} +\bookmark{\tex{partokencontext}} -Expands to the date string \PDFTEX\ uses in the info dictionary of the -document, \eg\ for this file {\tt\pdfcreationdate}. \introduced{1.30.0} +The {\em par-token} (i.e., the token with the name given by +\type{\partokenname}, or \type{\par} by default; see +\type{\partokenname}, next) is inserted into the input stream in +different places, according to the \type{\partokencontext} value. This +value can be: +0: {\em par-token} is inserted at empty lines (more exactly, when a + token category~5 is seen in state~$N$, reading a line); before + \type{\end}, \type{\vskip}, \type{\hrule}, \type{\unvbox}, and + \type{\halign}, if \TeX{} is in horizontal mode when those commands + are seen; and in various error recovery situations. These are the + standard cases, and this is the default value. -\pdftexprimitive{\Syntax{\tex {pdfdraftmode} \Whatever{integer}}} -\bookmark{\tex{pdfdraftmode}} +1: {\em par-token} is inserted as above, and also at the end of + \type{\vbox}, \type{\vtop}, and \type{\vcenter}, if \TeX{} is in + horizontal mode at the time. -When set to 1 (or set by the command-line switch \type{-draftmode}) -\PDFTEX\ doesn't write the output \PDF\ file and doesn't actually read any -images but does everything else (including writing auxiliary files), -thus speeding up compilations when you know you need an extra run but -don't care about the output, \eg\ just to get the \BIBTEX\ references -right. If specified, the parameter must appear before any data is written to the -\PDF\ output. +2: {\em par-token} is inserted as above, and also at the end of + \type{\insert}, \type{\vadjust}, \type{\output}, \type{\noalign}, and + items of \type{\valign}, again if \TeX{} is in horizontal mode at the + time. + +With the default \type{\partokencontext=0}, \TEX\ behaves in its normal +way: the situations in cases 1 and 2 are processed by a direct call of +{\em end-paragraph} routine, with no emitted {\em par-token}. + +If \type{\partokencontext=1} then \TeX\ inserts the {\em par-token} in +additional cases: when vertical boxes are completed but horizontal mode +is not finished. Since vboxes are not uncommonly inserted directly by +users, with horizontal mode material, this allows macro programmers to +control all such boxes being finished by a {\em par-token}. An example: + +\starttyping +\partokenname\_mypar +\partokencontext=1 +\def\_mypar{Hi there!\endgraf} +\vbox{Vbox text.} +\stoptyping + +This will output ``\type{Hi there!''}\ after ``\type{Vbox text.}''. + +Finally, with \type{\partokencontext=2}, all cases where classical \TeX\ +uses the direct {\em end-paragraph} routine are changed to emit the {\em +par-token} instead. In contrast to case~1, these commands are rarely +invoked directly by users with horizontal mode material. + +The setting of the register \type{\partokencontext} is local. +\introduced{1.40.24} + +\pdftexprimitive{\Syntax{\tex{partokenname} \Something{control sequence}}} +\bookmark{\tex{partokenname}} + +\TeX{} internally inserts a control sequence, named \type{\par} by +default, into the input stream at empty lines, the end of vboxes, and +various other places (see \type{\partokencontext}, above). Let's call this +control sequence the {\em par-token}. + +Executing \type{\partokenname}\Something{control-sequence} changes the +name of the {\em par-token} from \type{\par} to the given +\Something{control-sequence}. The setting performed by +\type{\partokenname} is global. + +This makes it possible to release the name \type{\par} to the ``user's +name space'', i.e., after \type{\partokenname}, users can define and use +\type{\par} as they wish without changing the behavior of anything +internal to \TeX{}. For example: + +\starttyping +\catcode`\_=11 +\partokenname\_mypar % use \_mypar at user level +\let\_mypar=\par % make \_mypar equivalent to built-in \par +% +\def\par{some random text} % redefine \par +% +Hello world. + +Goodbye. +\end +\stoptyping + +This will not output ``\type{some random text}'' (the definition of +\type{\par}), due to the \type{\partokenname} setting. + +By default, the meaning of the {\em par-token} is to end a paragraph +(also named as \type{\endgraf} in the plain \TEX\ format). It can be +changed as usual with, for example, \type{\def}. Naturally, it is the +control sequence name given to \type{\partokenname} that must be +redefined. Continuing the previous example (prior to the \type{\end}): + +\starttyping +\def\_mypar{Hi there!\endgraf} +Paragraph one. + +Paragraph two.\let\_mypar=\endgraf +\stoptyping + +This will output ``\type{Hi there!''}\ after ``\type{Paragraph one.}'', +before ending the paragraph. + +Another behavior of the {\em par-token} built into \TEX\ is that macros +not defined as \type{\long} cause the error ``runaway argument'' if the +{\em par-token} is scanned as a parameter. After +\type{\setpartokenname}, it will be the new control sequence name that +triggers this error, not \type{\par}. For example (still continuing the +same example): + +\starttyping +\def\amac#1{} +\amac{long test, no error: \par} +\amac{long test, gives error: \_mypar} +\stoptyping + +\introduced{1.40.24} + +\pdftexprimitive{\Syntax{\tex {pdfprimitive} \Something{control sequence}}} +\bookmark{\tex{pdfprimitive}} + +This command executes the primitive meaning of the following control +sequence, regardless of whether the control sequence has been redefined +or made undefined. If the primitive was expandable, \type{\pdfprimitive} +expands also. On the other hand, if the following control sequence never +was a primitive, nothing happens and no error is raised. (In some +versions of \PDFTEX\ prior to 1.40.19, an error was wrongly given.) \introduced{1.40.0} +%*********************************************************************** + +\subsection{Typesetting} \pdftexprimitive{\Syntax{\Tex{\pdfinsertht} \Something{integer} \Whatever{expandable}}} @@ -4495,26 +4190,6 @@ coordinate of the last point marked by \type{\pdfsavepos}. The unit is Completely analogous to \type{\pdflastxpos}, returning the $y$ coordinate. -\pdftexprimitive{\Syntax{\tex {pdfprimitive} \Something{control sequence}}} -\bookmark{\tex{pdfprimitive}} - -This command executes the primitive meaning of the following control -sequence, regardless of whether the control sequence has been redefined -or made undefined. If the primitive was expandable, \type{\pdfprimitive} -expands also. On the other hand, if the following control sequence never -was a primitive, nothing happens and no error is raised. (In some -versions of \PDFTEX\ prior to 1.40.19, an error was wrongly given.) -\introduced{1.40.0} - - -\pdftexprimitive{\Syntax{\Tex{\pdfretval} \Whatever{read||only integer}}} -\bookmark{\tex{pdfretval}} - -Set to $-1$ if \type{\pdfobj} ignores an invalid object number. Perhaps -this will be used to store the error status of other primitives in the -future. - - \pdftexprimitive{\Syntax{\Tex{\pdfsavepos} \Modelist{h, v, m}}} \bookmark{\tex{pdfsavepos}} @@ -4530,38 +4205,6 @@ runs are required to utilize these primitives. Starting with in \DVI\ mode. -\pdftexprimitive{\Syntax{\Tex{\pdfshellescape} \Whatever{read||only integer}}} -\bookmark{\tex{pdfshellescape}} - -This primitive is~1 if \type{\write18} is enabled, 2 if its operation is -restricted to known-safe programs, and 0 otherwise. \introduced{1.30.0} - - -\pdftexprimitive{\Syntax{\Tex{\pdftexbanner} \Whatever{expandable}}} -\bookmark{\tex{pdftexbanner}} - -Returns the \PDFTEX\ banner message, \eg\ for the version used here: -{\tt \pdftexbanner}. \introduced{1.20a} - - -\pdftexprimitive{\Syntax{\Tex{\pdftexrevision} \Whatever{expandable}}} -\bookmark{\tex{pdftexrevision}} - -\def\versplit#1#2#3{#1.#2#3} - -Returns the revision number of \PDFTEX, \eg\ for \PDFTEX\ version -\expandafter\versplit\the\pdftexversion.\pdftexrevision\ (used to produce -this document), it returns the number {\tt \pdftexrevision}. - - -\pdftexprimitive{\Syntax{\Tex{\pdftexversion} \Whatever{read||only integer}}} -\bookmark{\tex{pdftexversion}} - -Returns the version of \PDFTEX\ multiplied by 100, \eg\ for \PDFTEX\ -version \expandafter\versplit\the\pdftexversion.\pdftexrevision\ (used to -produce this document), it returns {\tt \number\pdftexversion}. - - \pdftexprimitive{\Syntax{\Tex{\quitvmode}}} \bookmark{\tex{quitvmode}} @@ -4573,6 +4216,28 @@ or may not be desired. \type{\quitvmode} does not expand \type{\everypar}. \introduced{1.21a} +\pdftexprimitive{\Syntax{\Tex{\vadjust} + \Optional{\Something{pre spec}} + \Something{filler} + \Lbrace \Something{vertical mode material} \Rbrace + \Modelist{h, m} +}} +\bookmark{\tex{vadjust}} + +The \type{\vadjust} implementation of \PDFTEX\ adds an optional +qualifier \Something{pre spec}, which is simply the string \type{pre}, to +the original \TEX\ primitive with the same name. If +no \type{pre} is given, \type{\vadjust} behaves exactly as the original +(see {\em The \TEX book}, p.~281): it appends an adjustment item created +from \Something{vertical mode material} to the current list {\em after} +the line in which \type{\vadjust} appears. In contrast, with the qualifier +\type{pre}, the adjustment item is put {\em before} the line in which +\type{\vadjust pre} appears. + +%*********************************************************************** + +\subsection{Tracing} + \pdftexprimitive{\Syntax{\Tex{\tracinglostchars} \Whatever{integer}}} \bookmark{\tex{tracinglostchars}} @@ -4658,27 +4323,93 @@ the prefix. The behavior is the same in all \TeX\ engines except the original \TEX\ and \eTeX, where \type{\tracingstacklevels} remains undefined. - \introduced{1.40.22} +\pdftexprimitive{\Syntax{\Tex{\showstream} \Whatever{integer}}} +\bookmark{\tex{showstream}} -\pdftexprimitive{\Syntax{\Tex{\vadjust} - \Optional{\Something{pre spec}} - \Something{filler} - \Lbrace \Something{vertical mode material} \Rbrace - \Modelist{h, m} -}} -\bookmark{\tex{vadjust}} +If this primitive parameter has a value corresponding to an open output +stream (which has been opened with \type{\openout}), then any +\type{\show}, \type{\showthe}, \type{\showbox} or \type{\showlists} +commands do not write output to the terminal, but instead write to only +the referenced output stream, as if they were written with +\type{\immediate\write}. -The \type{\vadjust} implementation of \PDFTEX\ adds an optional -qualifier \Something{pre spec}, which is simply the string \type{pre}, to -the original \TEX\ primitive with the same name. If -no \type{pre} is given, \type{\vadjust} behaves exactly as the original -(see {\em The \TEX book}, p.~281): it appends an adjustment item created -from \Something{vertical mode material} to the current list {\em after} -the line in which \type{\vadjust} appears. However, with the qualifier -\type{pre}, the adjustment item is put {\em before} the line in which -\type{\vadjust pre} appears. +For example: +\starttyping +\newwrite\myoutstream +\immediate\openout\myoutstream="infofile" +\showstream=\myoutstream +% From now on, \show... commands are redirected to "infofile.tex". +\show\TeX +% +\showstream=-1 +% -1 is never a open file and therefore restores +% normal \show... behavior. +\immediate\closeout\myoutstream +\stoptyping + +This example would not generate any special output to the terminal or +log file (except for any logging done by \type{\newwrite}. It writes +this text to \type{infofile.tex}, including the initial blank line, +since that is what \type{\show} does: + +\starttyping + +> \TeX=macro: +->T\kern -.1667em\lower .5ex\hbox {E}\kern -.125emX +\stoptyping + +The behavior is the same in all \TeX\ engines except the original \TEX\ +and \eTeX, where \type{\showstream} remains undefined. \introduced{1.40.24} + +%*********************************************************************** + +\subsection{\PDFTEX\ execution environment} + +\pdftexprimitive{\Syntax{\tex {pdfdraftmode} \Whatever{integer}}} +\bookmark{\tex{pdfdraftmode}} + +When set to 1 (or set by the command-line switch \type{-draftmode}) +\PDFTEX\ doesn't write the output \PDF\ file and doesn't actually read any +images but does everything else (including writing auxiliary files), +thus speeding up compilations when you know you need an extra run but +don't care about the output, \eg\ just to get the \BIBTEX\ references +right. If specified, the parameter must appear before any data is +written to the \PDF\ output. +\introduced{1.40.0} + + +\pdftexprimitive{\Syntax{\Tex{\pdfshellescape} \Whatever{read||only integer}}} +\bookmark{\tex{pdfshellescape}} + +This primitive is~1 if \type{\write18} is enabled, 2 if its operation is +restricted to known-safe programs, and 0 otherwise. \introduced{1.30.0} + + +\pdftexprimitive{\Syntax{\Tex{\pdftexbanner} \Whatever{expandable}}} +\bookmark{\tex{pdftexbanner}} + +Returns the \PDFTEX\ banner message, \eg\ for the version used here: +{\tt \pdftexbanner}. \introduced{1.20a} + + +\pdftexprimitive{\Syntax{\Tex{\pdftexrevision} \Whatever{expandable}}} +\bookmark{\tex{pdftexrevision}} + +\def\versplit#1#2#3{#1.#2#3} + +Returns the revision number of \PDFTEX, \eg\ for \PDFTEX\ version +\expandafter\versplit\the\pdftexversion.\pdftexrevision\ (used to produce +this document), it returns the number {\tt \pdftexrevision}. + + +\pdftexprimitive{\Syntax{\Tex{\pdftexversion} \Whatever{read||only integer}}} +\bookmark{\tex{pdftexversion}} + +Returns the version of \PDFTEX\ multiplied by 100, \eg\ for \PDFTEX\ +version \expandafter\versplit\the\pdftexversion.\pdftexrevision\ (used to +produce this document), it returns {\tt \number\pdftexversion}. %*********************************************************************** @@ -4781,6 +4512,61 @@ lacks any programming language commands, and cannot deal with arbitrary %*********************************************************************** +\section[sec.addpdfkeys]{Additional \PDF\ keys} + +{\em This section is based on the manual on keys written by Martin +Schr\"oder, one of the maintainers of \PDFTEX.} + +A \PDF\ document should contain only the structures and attributes defined +in the \PDF\ specification. However, the specification allows applications +to insert additional keys, provided they follow certain rules. + +The most important rule is that developers have to register with Adobe +prefixes for the keys they want to insert. Hans Hagen has registered the +prefix \type{PTEX} for \PDFTEX. + +\PDFTEX\ generates an XObject for every included \PDF. The dictionary of +this object contains these additional keys: + +\starttabulate[|lT|l|p|] +\HL +\NC \bf key \NC \bf type \NC meaning \NC \NR +\HL +\NC PTEX.FileName \NC string \NC The name of the included file as seen by + \PDFTEX. \NC \NR +\NC PTEX.InfoDict \NC dictionary \NC The document information dictionary of the included + \PDF\ (an indirect object). \NC \NR +\NC PTEX.PageNumber \NC integer \NC The page number of the included file. \NC \NR +\HL +\stoptabulate + +The \PDFReference\ says: \quotation {Although viewer applications can +store custom metadata in the document information dictionary, it is +inappropriate to store private content or structural information there; +such information should be stored in the document catalog instead.} + +Although it would seem more natural to put this information in the +document information dictionary, we have to obey the rules laid down in +the \PDFReference. The following key ends up in the document catalog. + +\starttabulate[|lT|l|p|] +\HL +\NC \bf key \NC \bf type \NC meaning \NC \NR +\HL +\NC PTEX.Fullbanner \NC string \NC The full version of the \pt binary that +produced the file as displayed by {\tt pdftex \hbox{-{}-version}}, \eg\ +{\tt\pdftexbanner}. This is necessary because the string in the +\type{Producer} key in the info dictionary is rather short, +namely {\tt pdfTeX-\currentpdftex}. \NC \NR +\HL +\stoptabulate + +Any or all of these keys can be suppressed with the +\type{\pdfsuppressptexinfo} primitive, described in +\in{section}[sec.docinfocatalog]. + +%*********************************************************************** + \section{Character translation} Characters that are input to \PDFTEX\ are subject to optional @@ -4826,21 +4612,506 @@ manual. %*********************************************************************** +\section{Installation} + +This section describes the steps needed to get \PDFTEX\ running on +a system where \PDFTEX\ is not yet installed. Nowadays essentially all +\TEX\ distributions include \PDFTEX\ already as a component, such as \TEXLIVE, +\MIKTEX, \PROTEXT, and \MACTEX. For example, the +\TEXLIVE\ distribution comes with \PDFTEX\ versions for many \UNIX, +\WIN, and \MACOSX\ systems; more information can be found at +\hbox{\from[texlive].} There are also \WIN-specific distributions which +contain \PDFTEX, under \from[win32]: \MIKTEX\ by Christian Schenk, and +\PROTEXT\ (based on \MIKTEX) by Thomas Feuerstack. When you use any +of these distributions, you don't need to bother with the \PDFTEX\ +installation procedure in the next sections. + +If there is no precompiled \PDFTEX\ binary for your system, or the version +coming with a distribution is not the current one and you would like to +try out a fresh \PDFTEX\ immediately, you will need to build \PDFTEX\ +from sources; read on. You should already have a working \TEX\ system, +\eg\ \TEXLIVE, into which the freshly compiled \PDFTEX\ will +be integrated. Note that the installation description in this manual +is \WEBC||specific. + +\subsection{Getting sources and binaries} + +The latest sources of \PDFTEX\ are distributed for compilation on \UNIX\ +systems (including \GNU/Linux), and \WIN\ systems. The primary home +page is \from[ptex_org], where you also find bug tracking information. +Development sources are at \from[ptex_devel]. Precompiled \PDFTEX\ +binaries for various systems might be available in subdirectories below +\from[ctan_systems], or via \TEX\ distribution web pages. + +%*********************************************************************** + +\subsection{Compiling} + +The compilation is expected to be easy on \UNIX||like systems and +can be described best by example. Assuming that the file \filename +{pdftex.zip} is downloaded to some working directory, \eg\ +\filename {\$HOME/pdftex}, on a \UNIX\ system the following steps are +needed to compile \PDFTEX: + +\startesctyping +cd pdftex.../source +./build-pdftex.sh +\stopesctyping + +The binary \filename{pdftex} is then built in the subdirectory +\filename{build/texk/web2c}. + +The obsolescent binary \filename{pdfetex} is still generated for backward +compatibility, but since version 1.40 it is just a symbolic link to or copy +of the file \filename{pdftex}. + +As well as the main \filename{pdftex} binary, binaries for the utilities +\filename{pdftosrc} and \filename{ttf2afm} are generated. + +Incidentally, for \PDFTEX\ maintains, a sibling script to +\type{build-pdftex.sh} is included, namely \type{sync-pdftex.sh}, which +syncs changes from a \TEXLIVE\ source repository to a \PDFTEX\ source +repository. Read the script before using it. And don't use it unless +you understand what you read. + +%*********************************************************************** + +\subsection{Placing files} + +The next step is to put the freshly compiled \filename{pdftex}, +\filename{pdftosrc}, and \filename{ttf2afm} binaries into the binary +directory (\eg\ for a typical \TEXLIVE\ system, and on the appropriate +platform) \filename{/usr/local/texlive/\rcsyear/bin/x86_64-linux}. + +If you're doing this into a live hierarchy, don't forget to do a +\type{texconfig-sys init} afterwards, so that all formats are +regenerated system-wide with the fresh \filename{pdftex} binary. + +%*********************************************************************** + +\subsection{Setting search paths} + +\WEBC||based programs, including \PDFTEX, use the \WEBC\ run||time +configuration file called \filename {texmf.cnf}. The location +of this file is the appropriate position within the \TDS\ tree +relative to the place of the \PDFTEX\ binary; on a \TEXLIVE\ system, +\filename{texmf.cnf} is typically located either in the directory +\filename{texmf-dist/web2c}. The path to +file \filename{texmf.cnf} can also be set up by the environment variable +\type{TEXMFCNF}. + +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. + +\PDFTEX\ uses the search path variables shown in +\in{table}[tbl:spathvar], among others. + +\startbuffer +\starttabulate[|l|l|] +\HL +\NC \bf used for \NC \bf texmf.cnf \NC\NR +\HL +\NC output files \NC \type{TEXMFOUTPUT} \NC\NR +\NC input files, images \NC \type{TEXINPUTS} \NC\NR +\NC format files \NC \type{TEXFORMATS} \NC\NR +\NC \TeX\ pool files \NC \type{TEXPOOL} \NC\NR +\NC encoding files \NC \type{ENCFONTS} \NC\NR +\NC font map files \NC \type{TEXFONTMAPS} \NC\NR +\NC \TFM\ files \NC \type{TFMFONTS} \NC\NR +\NC virtual fonts \NC \type{VFFONTS} \NC\NR +\NC Type~1 fonts \NC \type{T1FONTS} \NC\NR +\NC TrueType fonts \NC \type{TTFONTS} \NC\NR +\NC OpenType fonts \NC \type{OPENTYPEFONTS} \NC\NR +\NC bitmap fonts \NC \type{PKFONTS} \NC\NR +\HL +\stoptabulate +\stopbuffer + +\placetable[here][tbl:spathvar] + {The principal \WEBC\ variables.} + {\getbuffer} + +\PathDescription {TEXMFOUTPUT} Normally, \PDFTEX\ puts its output files +in the current directory, overridden by the \type{-output-directory} +option. If any output file cannot be opened there, it tries to open it +in the environment variable \type{TEXMFOUTPUT}, if that is set. There is +no default value for that variable. For example, if \type{TEXMFOUTPUT} +has the value \type{/tmp}, and you run \type{pdftex paper} when the +current directory is not writable, \PDFTEX\ attempts to create +\type{/tmp/paper.log} (and \type{/tmp/paper.pdf}, etc.) + +\PathDescription {TEXINPUTS} This variable specifies where \PDFTEX\ finds +its input files. Image files are considered +input files and searched for along this path. + +\PathDescription {TEXFORMATS} Search path for format (\type{.fmt}) files. + +\PathDescription {TEXPOOL} Search path for pool (\type{.pool}) files; no +longer used, since the pool file (program strings) are compiled into +the binary. + +\PathDescription {ENCFONTS} Search path for encoding (\type{.enc}) files. + +\PathDescription {TEXFONTMAPS} Search path for font map (\type{.map}) files. + +\PathDescription {TFMFONTS} Search path for font metric (\type{.tfm}) files. + +\PathDescription {VFFONTS} Search path for virtual font (\type{.vf}) +files. Virtual fonts are fonts made up of other fonts. +Because \PDFTEX\ produces the +final output code, it must consult those files. + +\PathDescription {T1FONTS} Search path for Type~1 font files (\type{.pfa} +and \type{.pfb}). These outline (vector) fonts are to be preferred over +bitmap \PK\ fonts. In most cases Type~1 fonts are used and this variable +tells \PDFTEX\ where to find them. + +\PathDescription {TTFONTS,\hfil\break \hbox{OPENTYPEFONTS}} Search paths +for TrueType (\type{.ttf}) and OpenType (\type{.otf}) font files. Like +Type~1 fonts, TrueType and OpenType fonts are also outlines. + +\PathDescription {PKFONTS} Search path for packed (bitmap) font +(\type{.pk}) files. +Unfortunately bitmap fonts are still displayed poorly by some \PDF\ +viewers, so when possible one should use outline fonts. When no outline +is available, \PDFTEX\ tries to locate a suitable \PK\ font (or invoke +a process that generates it). + +\PathDescription{TEXFONTS} Fallback for all the font paths, so that if +you want to look in a particular directory for fonts on a given run, you +can set that one variable. + +Many more variables may be consulted, and there are many details to +file name lookups. See the Kpathsea manual (\from [kpathsea]). + +%*********************************************************************** + +\subsection[cfg]{The \PDFTEX\ configuration} + +We must keep in mind that, as opposed to \TEX\ with its \DVI\ output, +the \PDFTEX\ program does not have a separate postprocessing stage to +transform the \TEX\ input into final \PDF. As a consequence, all data +needed for building a ready \PDF\ page must be available during the +\PDFTEX\ run, in particular information on media dimensions and offsets, +graphics files for embedding, and font information (font files, +encodings). + +When \TEX\ builds a page, it places items relative to the (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. + +In \PDF, the paper dimensions are part of the page definition, and +\PDFTEX\ therefore requires that they be defined at the beginning of +the \PDFTEX\ run. As with pages described by \POSTSCRIPT, the \PDF\ +reference point is in the lower||left corner. + +Formerly, these dimensions and other \PDFTEX\ parameters were read +in from a configuration file named \filename{pdftex.cfg}, which had +a special (non-\TEX) format, at the start of processing. Nowadays such +a file is ignored by \PDFTEX. Instead, the page dimensions and offsets, +as well as many other parameters, can be set by \PDFTEX\ primitives +during the \PDFTEX\ format building process, so that the settings are +dumped into the fresh format and consequently will be used when \PDFTEX\ +is later called with that format. All settings from the format can +still be overridden during a \PDFTEX\ run by using the same primitives. +This new configuration concept is a more unified approach, as it avoids +the configuration file with a special format. + +A list of \PDFTEX\ primitives relevant to setting up the \PDFTEX\ engine +is given in \in{table}[tbl:configparms]. All primitives are described in +detail within later sections. \in{Figure}[in:pdftexconfig] shows a recent +configuration file (\type{pdftexconfig.tex}) in \TEX\ format, using the +primitives from \in{table}[tbl:configparms], which typically is read +in during the format building process. It enables \PDF\ output, sets paper +dimensions and the default pixel density for \PK\ font inclusion. The default +values are chosen so that \PDFTEX\ often can be used (\eg\ in \type{-ini} mode) +even without setting any parameters. + +\startbuffer +\starttabulate[|l|l|l|l|l|] +\HL +\NC \bf internal name \NC \bf type \NC\bf default\NC\bf comment\NC\NR +\HL +\NC \type{\pdfoutput} \NC integer \NC 0 \NC \DVI \NC\NR +\NC \type{\pdfadjustspacing} \NC integer \NC 0 \NC off \NC\NR +\NC \type{\pdfcompresslevel} \NC integer \NC 9 \NC best \NC\NR +\NC \type{\pdfobjcompresslevel} \NC integer \NC 0 \NC no object streams \NC\NR +\NC \type{\pdfdecimaldigits} \NC integer \NC 4 \NC max. \NC\NR +\NC \type{\pdfimageresolution} \NC integer \NC 72 \NC dpi \NC\NR +\NC \type{\pdfpkresolution} \NC integer \NC 0 \NC 72\,dpi \NC\NR +\NC \type{\pdfpkmode} \NC token reg.\NC empty \NC mode set in \type{mktex.cnf} \NC\NR +\NC \type{\pdfuniqueresname} \NC integer \NC 0 \NC \NC\NR +\NC \type{\pdfprotrudechars} \NC integer \NC 0 \NC \NC\NR +\NC \type{\pdfgentounicode} \NC integer \NC 0 \NC \NC\NR +\NC \type{\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 +\HL +\stoptabulate +\stopbuffer + +\placetable[here][tbl:configparms] + {The set of \PDFTEX\ configuration parameters.} + {\getbuffer} + +\startbuffer +\tx\setupinterlinespace +\startframedtext +\starttyping +% tex-ini-files 2016-04-15: pdftexconfig.tex + +% Load shared (PDF) settings in pdfTeX + +% Enable PDF output +\pdfoutput = 1 + +% Paper size: dimensions given in absolute terms +\pdfpageheight = 11 true in +\pdfpagewidth = 8.5 true in + +% Enable PDF 1.5 output and thus more compression +\pdfminorversion = 5 +\pdfobjcompresslevel = 2 + +% Low-level settings unlikely ever to need to change +\pdfcompresslevel = 9 +\pdfdecimaldigits = 3 +\pdfpkresolution = 600 +\pdfhorigin = 1 true in +\pdfvorigin = 1 true in +\stoptyping +\stopframedtext +\stopbuffer + +\placefigure[here][in:pdftexconfig] + {\PDFTEX\ configuration file for \TEXLIVE\ (\filename{pdftexconfig.tex}).} + {\getbuffer} + +Independent of whether such a configuration file is read or not, the +first action in a \PDFTEX\ run is that the program reads the global +\WEBC\ configuration file (\filename{texmf.cnf}), which is common to all +programs in the \WEBC\ system. This file mainly defines file search +paths, the memory layout (\eg\ string pool and hash size), and a few +other general parameters. + +%*********************************************************************** + +\subsection{Creating format files} + +\startbuffer +\tx\setupinterlinespace +\startframedtext +\starttyping +% Thomas Esser, 1998. public domain. +\input etex.src +\dump +\endinput +\stoptyping +\stopframedtext +\stopbuffer + +\placefigure[here][in:etexini] + {File \type{etex.ini} for the plain \ETEX\ format with \DVI\ output.} + {\getbuffer} + +\startbuffer +\tx\setupinterlinespace +\startframedtext +\starttyping +% Thomas Esser, 1998. public domain. +% This is used for pdftex and pdfetex, which are now identical: +% both with e-TeX extensions, both with pdf (and dvi) output. +\input pdftexconfig.tex +\input etex.src +\input pdftexmagfix.tex +\dump +\endinput +\stoptyping +\stopframedtext +\stopbuffer + +\placefigure[here][in:pdfetexini] + {File \type{pdfetex.ini} for plain \ETEX\ with \PDF\ output.} + {\getbuffer} + +\startbuffer +\tx\setupinterlinespace +\startframedtext +\starttyping +% Thomas Esser, 1998. public domain. +\input pdftexconfig.tex +\scrollmode +\input latex.ltx +\endinput +\stoptyping +\stopframedtext +\stopbuffer + +\placefigure[here][in:pdflatexini] + {File \type{pdflatex.ini} for the \LATEX\ format with \PDF\ output.} + {\getbuffer} + +The \PDFTEX\ engine supports building formats for \DVI\ and \PDF\ output +in the same way as the classical \TEX\ engine does for \DVI. Format +generation (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. + +It is customary to package the configuration and macro file input +into a \type{.ini} file. \Eg, the file \type{etex.ini} in +\in{figure}[in:etexini] is for generating an \ETEX\ format with \DVI\ +output. It has been traditional for many years to generate +\type{etex.fmt} with \PDFTEX\ rather than the original \ETEX, because +\PDFTEX\ contains a few additional programming and other +non-\PDF-related features on which people have come to rely. + +The \type{pdfetex.ini} file \in{figure}[in:etexini] shows the +corresponding format with \PDF\ output by default; this is what creates +the format file read when \type{pdftex} is normally invoked. + +Finally, \type{pdflatex.ini} \in{figure}[in:pdflatexini] shows how the +\LATEX\ format with \PDF\ output by default is generated. + +The corresponding \PDFTEX\ calls for format generation are: + +\starttyping +pdftex -ini *etex.ini +pdftex -ini *pdfetex.ini +pdftex -ini *pdflatex.ini +\stoptyping + +These calls produce format files \filename{etex.fmt}, +\filename{pdfetex.fmt}, and \filename{pdflatex.fmt}, as the default +format file name is taken from the input file name. You can 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. + +\subsection{Testing the installation} + +When everything is set up, you can test the installation. A simple test +of plain \PDFTEX\ is: + +\starttyping +pdftex story \\end +\stoptyping + +This should typeset the famous one-page short story by A.U. Thor. + +A more thorough and descriptive test is the plain \TEX\ test file +\filename{samplepdf.tex}, available in the distribution in the +\type{samplepdftex/} directory. Process this file by typing: + +\starttyping +pdftex samplepdf +\stoptyping + +If the installation is ok, this should produce a file called +\filename{samplepdf.pdf}. The file \filename {samplepdf.tex} is a good +place to look for examples of how to use \PDFTEX's primitives. + +%*********************************************************************** + +\subsection{Common problems} + +The most common problem with installations is that \PDFTEX\ complains +that something cannot be found. In such cases make sure that +\type{TEXMFCNF} is set correctly, so \PDFTEX\ can find \filename +{texmf.cnf}. The next best place to look|/|edit is the file +\type{texmf.cnf}. When still in deep trouble, set +\type{KPATHSEA_DEBUG=255} before running \PDFTEX\ or use the option +\type{-kpathsea-debug 255}. This will cause \PDFTEX\ to write a lot of +debugging information that can be useful to trace problems. More options +can be found in the \WEBC\ documentation. + +Variables in \filename {texmf.cnf} can be overwritten by environment +variables. Here are some of the most common problems you can encounter when +getting started: + +\startitemize + +\head \type{I can't find the format file `pdftex.fmt'!} \crlf + \type{I can't find the format file `pdflatex.fmt'!} + + The format file is not created (see above how to do that) or + is not properly placed. Make sure that \type{TEXFORMATS} in + \filename {texmf.cnf} contains the path to \filename {pdftex.fmt} + or \filename {pdflatex.fmt}. + +\head \type{Fatal format file error; I'm stymied} + + This appears \eg\ if you forgot to regenerate the \type{.fmt} + files after installing a new version of the \PDFTEX\ binary. + The first line tells by which engine the offending format was generated. + +\head \PDFTEX\ cannot find one or more map files (\type{*.map}), + encoding vectors (\type{*.enc}), virtual fonts, Type~1 fonts, + TrueType or OpenType fonts, or some image file. + + Make sure that the required file exists and the corresponding variable + in \filename {texmf.cnf} contains a path to the file. See above which + variables \PDFTEX\ needs apart from the ones \TEX\ uses. + + When you have installed new fonts, and your \PDF\ viewer complains + about missing fonts, you should take a look at the log file produced + by \PDFTEX. Missing fonts, map files, encoding vectors as well as + missing characters (glyphs) are reported there. + +\stopitemize + +Normally the page content takes one object. This means that one seldom +finds more than a few hundred objects in a simple file. This \PDFTEX\ +manual for instance uses approx.~750 objects. In more complex applications +this number can grow quite rapidly, especially when one uses a lot of +widget annotations, shared annotations or other shared things. In any +case \PDFTEX's internal object table size will automatically grow to the +required size (the parameter \type{obj_tab_size} for manual control of +the object table size is now obsolete and ignored). + +%*********************************************************************** + \stopbodymatter -%D We did use some abbreviations. Only those really used will end up in the -%D following list. +%D Only abbreviations actually used will end up in the following list. \startbackmatter \writebetweenlist[section]{\blank[line]} -%*********************************************************************** - \section{Abbreviations} -In this document we use numerous abbreviations. For convenience we mention -their meaning here. +In this document we use numerous abbreviations. For convenience we give +their meanings here. \placelistofabbreviations @@ -4875,61 +5146,6 @@ to one of the maintainers. %*********************************************************************** -\section[sec.addpdfkeys]{Additional \PDF\ keys} - -{\em This section is based on the manual on keys written by Martin -Schr\"oder, one of the maintainers of \PDFTEX.} - -A \PDF\ document should contain only the structures and attributes defined -in the \PDF\ specification. However, the specification allows applications -to insert additional keys, provided they follow certain rules. - -The most important rule is that developers have to register with Adobe -prefixes for the keys they want to insert. Hans Hagen has registered the -prefix \type{PTEX} for \PDFTEX. - -\PDFTEX\ generates an XObject for every included \PDF. The dictionary of -this object contains these additional keys: - -\starttabulate[|lT|l|p|] -\HL -\NC \bf key \NC \bf type \NC meaning \NC \NR -\HL -\NC PTEX.FileName \NC string \NC The name of the included file as seen by - \PDFTEX. \NC \NR -\NC PTEX.InfoDict \NC dictionary \NC The document information dictionary of the included - \PDF\ (an indirect object). \NC \NR -\NC PTEX.PageNumber \NC integer \NC The page number of the included file. \NC \NR -\HL -\stoptabulate - -The \PDFReference\ says: \quotation {Although viewer applications can -store custom metadata in the document information dictionary, it is -inappropriate to store private content or structural information there; -such information should be stored in the document catalog instead.} - -Although it would seem more natural to put this information in the -document information dictionary, we have to obey the rules laid down in -the \PDFReference. The following key ends up in the document catalog. - -\starttabulate[|lT|l|p|] -\HL -\NC \bf key \NC \bf type \NC meaning \NC \NR -\HL -\NC PTEX.Fullbanner \NC string \NC The full version of the \pt binary that -produced the file as displayed by {\tt pdftex \hbox{-{}-version}}, \eg\ -{\tt\pdftexbanner}. This is necessary because the string in the -\type{Producer} key in the info dictionary is rather short, -namely {\tt pdfTeX-\currentpdftex}. \NC \NR -\HL -\stoptabulate - -Any or all of these keys can be suppressed with the -\type{\pdfsuppressptexinfo} primitive, described in -\in{section}[sec.docinfocatalog]. - -%*********************************************************************** - \section{Colophon} This manual is typeset in \CONTEXT. One can generate an A4 version from @@ -4957,9 +5173,6 @@ Odd and even page sets for non-duplex printers can be generated using \type{-}\type{-pages=odd} and \type{-}\type{-pages=even} options (which might require some disciplined shuffling of sheet). -This also demonstrates that \PDFTEX\ can be used for page imposition -purposes (given that \PDFTEX\ and the fonts are set up properly). - %*********************************************************************** \page @@ -4974,7 +5187,7 @@ purposes (given that \PDFTEX\ and the fonts are set up properly). \section{GNU Free Documentation License} \startnotmode[screen] - \switchtobodyfont[4.6pt] % squeeze everything on one page :-} + \switchtobodyfont[6.4pt] % squeeze everything onto two pages} \setuplayout[grid=yes] \setupcolumns[n=7] \stopnotmode |