pdftex[856] branches/stable/doc/manual: split Miscellanous primitives

commits+karl at tug.org commits+karl at tug.org
Sat Jul 24 19:26:38 CEST 2021


Revision: 856
          http://tug.org/svn/pdftex?view=revision&revision=856
Author:   karl
Date:     2021-07-24 19:26:37 +0200 (Sat, 24 Jul 2021)
Log Message:
-----------
split Miscellanous primitives subsection; move Installation to end

Modified Paths:
--------------
    branches/stable/doc/manual/ChangeLog
    branches/stable/doc/manual/pdftex-t.tex

Modified: branches/stable/doc/manual/ChangeLog
===================================================================
--- branches/stable/doc/manual/ChangeLog	2021-06-17 21:27:03 UTC (rev 855)
+++ branches/stable/doc/manual/ChangeLog	2021-07-24 17:26:37 UTC (rev 856)
@@ -1,3 +1,12 @@
+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: branches/stable/doc/manual/pdftex-t.tex
===================================================================
--- branches/stable/doc/manual/pdftex-t.tex	2021-06-17 21:27:03 UTC (rev 855)
+++ branches/stable/doc/manual/pdftex-t.tex	2021-07-24 17:26:37 UTC (rev 856)
@@ -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?
 
@@ -830,496 +829,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
@@ -2328,7 +1837,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 +1983,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}}
 
@@ -3318,6 +2834,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}
@@ -4380,6 +3904,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 +3945,10 @@
 
 %***********************************************************************
 
-\subsection{Miscellaneous}
+\subsection{Macro programming}
 
+Expansion-related.
+
 \pdftexprimitive{\Syntax{\tex {expanded} \Something{tokens}
   \Whatever{expandable}}}
 \bookmark{\tex{expanded}}
@@ -4430,6 +3958,7 @@
 be doubled. \type{\protected} macros are not expanded.
 \introduced{1.40.20}
 
+
 \pdftexprimitive{\Syntax{\tex {ifincsname} \Whatever{expandable}}}
 \bookmark{\tex{ifincsname}}
 
@@ -4447,26 +3976,21 @@
 primitive) false is returned.  \introduced{1.40.0}
 
 
-\pdftexprimitive{\Syntax{\Tex{\pdfcreationdate} \Whatever{expandable}}}
-\bookmark{\tex{pdfcreationdate}}
+\pdftexprimitive{\Syntax{\tex {pdfprimitive} \Something{control sequence}}}
+\bookmark{\tex{pdfprimitive}}
 
-Expands to the date string \PDFTEX\ uses in the info dictionary of the
-document, \eg\ for this file {\tt\pdfcreationdate}. \introduced{1.30.0}
+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 {pdfdraftmode} \Whatever{integer}}}
-\bookmark{\tex{pdfdraftmode}}
+\subsection{Typesetting}
 
-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{\pdfinsertht} \Something{integer}
   \Whatever{expandable}}}
 \bookmark{\tex{pdfinsertht}}
@@ -4495,26 +4019,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 +4034,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 +4045,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}}
 
@@ -4661,25 +4155,54 @@
 
 \introduced{1.40.22}
 
+%***********************************************************************
 
-\pdftexprimitive{\Syntax{\Tex{\vadjust}
-  \Optional{\Something{pre spec}}
-  \Something{filler}
-  \Lbrace \Something{vertical mode material} \Rbrace
-  \Modelist{h, m}
-}}
-\bookmark{\tex{vadjust}}
+\subsection{\PDFTEX\ execution environment}
 
-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.
+\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}
@@ -4781,6 +4304,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 +4404,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 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 +4938,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



More information about the pdftex-commits mailing list.