texlive[62306] Master/texmf-dist/doc/pdftex/manual: pdftex manual
commits+karl at tug.org
commits+karl at tug.org
Tue Mar 1 03:09:14 CET 2022
Revision: 62306
http://tug.org/svn/texlive?view=revision&revision=62306
Author: karl
Date: 2022-03-01 03:09:14 +0100 (Tue, 01 Mar 2022)
Log Message:
-----------
pdftex manual update for 1.40.24 (TeX Live 2022)
Modified Paths:
--------------
trunk/Master/texmf-dist/doc/pdftex/manual/ChangeLog
trunk/Master/texmf-dist/doc/pdftex/manual/Makefile
trunk/Master/texmf-dist/doc/pdftex/manual/pdftex-a.pdf
trunk/Master/texmf-dist/doc/pdftex/manual/pdftex-syntax.txt
trunk/Master/texmf-dist/doc/pdftex/manual/pdftex-t.tex
Modified: trunk/Master/texmf-dist/doc/pdftex/manual/ChangeLog
===================================================================
--- trunk/Master/texmf-dist/doc/pdftex/manual/ChangeLog 2022-03-01 00:28:48 UTC (rev 62305)
+++ trunk/Master/texmf-dist/doc/pdftex/manual/ChangeLog 2022-03-01 02:09:14 UTC (rev 62306)
@@ -1,3 +1,46 @@
+2022-02-28 Karl Berry <karl at freefriends.org>
+
+ * pdftex-t.tex (ptex_devel): svn://tug.org url.
+
+2021-11-06 Marcel Kr\"uger <tex at 2krueger.de>
+
+ * pdftex-t.tex (\showstream): document.
+
+2021-11-06 Marcel Kr\"uger <tex at 2krueger.de>
+
+ * pdftex-t.tex: missed bookmarks for \pdfgentounicode and
+ a few other primitives.
+
+2021-11-04 Karl Berry <karl at 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 at 2krueger.de>
+
+ * pdftex-t.tex: document structured destinations (\pdfdest struct NNN).
+ Also bump document font size to 11pt.
+
+2021-09-25 Karl Berry <karl at freefriends.org>
+
+ * pdftex-t.tex (\pdfstartlink): organize into lists.
+
+2021-07-25 Karl Berry <karl at 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 at 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 at freefriends.org>
* pdftex-t.tex: update for 2021:
Modified: trunk/Master/texmf-dist/doc/pdftex/manual/Makefile
===================================================================
--- trunk/Master/texmf-dist/doc/pdftex/manual/Makefile 2022-03-01 00:28:48 UTC (rev 62305)
+++ trunk/Master/texmf-dist/doc/pdftex/manual/Makefile 2022-03-01 02:09:14 UTC (rev 62306)
@@ -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 @@
#
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 @@
rm -f pdftex-w.pdf pdftex-w.txt
clobber allclean realclean distclean: maintainer-clean
+
+spell:
+ myspell pdftex-t.tex
Modified: trunk/Master/texmf-dist/doc/pdftex/manual/pdftex-a.pdf
===================================================================
(Binary files differ)
Modified: trunk/Master/texmf-dist/doc/pdftex/manual/pdftex-syntax.txt
===================================================================
--- trunk/Master/texmf-dist/doc/pdftex/manual/pdftex-syntax.txt 2022-03-01 00:28:48 UTC (rev 62305)
+++ trunk/Master/texmf-dist/doc/pdftex/manual/pdftex-syntax.txt 2022-03-01 02:09:14 UTC (rev 62306)
@@ -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>
Modified: trunk/Master/texmf-dist/doc/pdftex/manual/pdftex-t.tex
===================================================================
--- trunk/Master/texmf-dist/doc/pdftex/manual/pdftex-t.tex 2022-03-01 00:28:48 UTC (rev 62305)
+++ trunk/Master/texmf-dist/doc/pdftex/manual/pdftex-t.tex 2022-03-01 02:09:14 UTC (rev 62306)
@@ -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,8 +73,8 @@
\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}
@@ -81,9 +81,9 @@
\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 at tug.org] [] [pdftex at 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 @@
\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 @@
%***********************************************************************
-\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 @@
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 @@
\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 @@
\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 @@
%***********************************************************************
-\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 @@
} 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 @@
\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 @@
\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 @@
\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 @@
\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 @@
\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 @@
\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 @@
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,27 +3426,70 @@
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}.
+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}.
-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.
+\startitemize
-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.
+\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 @@
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 @@
\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,8 +3999,10 @@
%***********************************************************************
-\subsection{Miscellaneous}
+\subsection{Macro programming}
+Expansion-related.
+
\pdftexprimitive{\Syntax{\tex {expanded} \Something{tokens}
\Whatever{expandable}}}
\bookmark{\tex{expanded}}
@@ -4430,6 +4012,7 @@
be doubled. \type{\protected} macros are not expanded.
\introduced{1.40.20}
+
\pdftexprimitive{\Syntax{\tex {ifincsname} \Whatever{expandable}}}
\bookmark{\tex{ifincsname}}
@@ -4447,26 +4030,138 @@
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}}}
\bookmark{\tex{pdfinsertht}}
@@ -4495,26 +4190,6 @@
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 @@
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 @@
\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,30 +4323,96 @@
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}.
+
+%***********************************************************************
+
\section{Graphics}
\PDFTEX\ supports inclusion of pictures in \PNG, \JPEG, \JBIGTWO, and
@@ -4781,6 +4512,61 @@
%***********************************************************************
+\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 @@
%***********************************************************************
+\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 @@
%***********************************************************************
-\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 @@
\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 @@
\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
More information about the tex-live-commits
mailing list.