summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/pdftex/manual/pdftex-t.tex
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2014-04-24 17:15:59 +0000
committerKarl Berry <karl@freefriends.org>2014-04-24 17:15:59 +0000
commitc8a6de14b993dc57612be5e4310ced63a6113937 (patch)
tree4fc4b3271033e296383cf2a46058e8546c2836a2 /Master/texmf-dist/doc/pdftex/manual/pdftex-t.tex
parent230c21255ab9100d32332550cad586950122fb78 (diff)
update pdftex manual for 1.40.15
git-svn-id: svn://tug.org/texlive/trunk@33656 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/pdftex/manual/pdftex-t.tex')
-rw-r--r--Master/texmf-dist/doc/pdftex/manual/pdftex-t.tex413
1 files changed, 258 insertions, 155 deletions
diff --git a/Master/texmf-dist/doc/pdftex/manual/pdftex-t.tex b/Master/texmf-dist/doc/pdftex/manual/pdftex-t.tex
index 6c99763f8ea..b937b6112f5 100644
--- a/Master/texmf-dist/doc/pdftex/manual/pdftex-t.tex
+++ b/Master/texmf-dist/doc/pdftex/manual/pdftex-t.tex
@@ -1,7 +1,7 @@
% interface=english modes=letter,screen output=pdftex
% vim: tw=79
-% $Id: pdftex-t.tex 655 2010-11-23 00:37:25Z karl $
+% $Id: pdftex-t.tex 711 2014-04-23 22:56:07Z karl $
% The number of lines on the titlepage depends on exactly
% what \PDF\ code is generated.
@@ -12,19 +12,15 @@
%D to generate an A4, letter and screen version.
%D
%D Default A4 size manual:
-%D
%D texexec --result=pdftex-a.pdf pdftex-t
%D
%D Letter size manual:
-%D
%D texexec --mode=letter --result=pdftex-l.pdf pdftex-t
%D
%D Booklet (given that A4 document is available):
-%D
%D texexec --pdfarrange --paper=a5a4 --print=up --addempty=1,2 --result=pdftex-b.pdf pdftex-a
%D
%D Screen version
-%D
%D texexec --mode=screen pdftex-t
%D This is the \PDFTEX\ manual, so it makes sense to force \PDF\ output here.
@@ -61,16 +57,16 @@
July\or August\or September\or October\or November\or December\else ERROR\fi}
}
-\svnscan $Id: pdftex-t.tex 655 2010-11-23 00:37:25Z karl $
+\svnscan $Id: pdftex-t.tex 711 2014-04-23 22:56:07Z karl $
-\def\currentpdftex{1.40.11}
+\def\currentpdftex{1.40.15}
%***********************************************************************
\def\eTeX{{$\varepsilon$}-\kern-.125em\TeX}
-\def\eg{e.\,g.}
-\def\Eg{E.\,g.}
-\def\PDFReference{PDF Reference} % PDF with capital letters
+\def\eg{e.g.}
+\def\Eg{E.g.}
+\def\PDFReference{{\sl PDF Reference}} % PDF with capital letters
\abbreviation [AFM] {afm} {Adobe Font Metrics}
%\abbreviation [AMIGA] {Amiga} {Amiga hardware platform}
@@ -148,13 +144,12 @@
%D appearance of the \TEX\ source, \URL's are defined here.
\useURL [ptex_org] [http://www.pdftex.org] % links to ptex_examples
-\useURL [ptex_ctan] [http://mirror.ctan.org/systems/pdftex]
-\useURL [ptex_devel] [http://foundry.supelec.fr/gf/project/pdftex]
+\useURL [ptex_ctan] [http://ctan.org/pkg/pdftex]
+\useURL [ptex_devel] [http://foundry.supelec.fr/projects/pdftex]
% where bug reports should go:
-\useURL [ptex_bugs] [mailto:pdftex@tug.org] [] [pdftex@tug.org]
-% anything else pdftex related:
-\useURL [ptex_list] [mailto:pdftex@tug.org] [] [pdftex@tug.org]
+\useURL [ptex_bugs] [mailto:pdftex@tug.org] [] [pdftex@tug.org]
+\useURL [ptex_listinfo] [http://lists.tug.org/pdftex]
\useURL [texlive] [http://tug.org/texlive/]
\useURL [ctan_systems] [http://mirror.ctan.org/systems]
@@ -402,7 +397,7 @@
openaction=firstpage,
title=the pdfTeX users manual,
author={H\`an Th\^e Th\`anh, Sebastian Rahtz, Hans Hagen, Hartmut Henkel,
- Pawe\l\ Jackowski, Martin Schr\"oder}]
+ Pawe\l\ Jackowski, Martin Schr\"oder, Karl Berry}]
\setupinteractionscreen % still needed?
@@ -617,7 +612,7 @@
\pdfoutput=1
\pdfcompresslevel=0
\pdfobjcompresslevel=0
- \pdfmapline{ptmr8r Times-Roman <8r.enc}
+ \pdfmapline{ptmr8r Times-Roman 2 <8r.enc}
\font\tenrm=ptmr8r
\tenrm
Welcome to pdf\TeX!
@@ -656,18 +651,18 @@ The main purpose of the \PDFTEX\ project is to create and maintain
an extension of \TEX\ that can produce \PDF\ directly from \TEX\
source files and improve|/|enhance the result of \TEX\ typesetting
with the help of \PDF. When \PDF\ output is not selected, \PDFTEX\
-produces normal \DVI\ output, otherwise it generates \PDF\ output
+produces standard \DVI\ output, otherwise it generates \PDF\ output
that looks identical to the \DVI\ output. An important aspect of this
project is to investigate alternative justification algorithms (\eg\
a font expansion algorithm akin to the \HZ\ micro||typography algorithm by
-Prof.~Hermann Zapf), optionally making use of Multiple Master fonts.
+Prof.~Hermann Zapf).
\PDFTEX\ is based on the original \TEX\ sources and \WEBC, and has been
successfully compiled on \UNIX, \WIN\ and \MSDOS\ systems. It is
actively maintained, with new features trickling in. Great care is taken
to keep new \PDFTEX\ versions backward compatible with earlier ones.
-For some years there has been a \quote {moderate} successor to \TEX\
+For some years there has been a \quote {conservative} successor to \TEX\
available, called \ETEX. Because mainstream macro packages such as
\LATEX\ have started supporting this welcome extension, the \ETEX\
functionality has also been integrated into the \PDFTEX\ code. For a
@@ -681,26 +676,18 @@ of \PDFTEX\ can be disabled if not required. Other extensions are
\MLTEX\ and \ENCTEX; these are also included in the current \PDFTEX\
code.
-\PDFTEX\ is maintained by \THANH, Martin Schr\"oder, Hans Hagen, Taco
-Hoekwater, Hartmut Henkel, and others. The \PDFTEX\ homepage is \from
-[ptex_org]. Please send \PDFTEX\ comments and bug reports to the mailing
-list \from [ptex_bugs].
-
-We thank all readers who send us corrections and suggestions. We also
-wish to express the hope that \PDFTEX\ will be of as much use to you
-as it is to us. Since \PDFTEX\ is still being improved and extended,
-we strongly suggest tracking updates.
+\PDFTEX\ is maintained by \THANH, Martin Schr\"oder, and others. The
+\PDFTEX\ homepage is \from [ptex_org]. Please send \PDFTEX\ comments and
+bug reports to the mailing list \from [ptex_bugs] (\from [ptex_listinfo]).
%***********************************************************************
\subsection{About this manual}
-This manual revision (\rcsrevision) tries to keep track with the recent
-\PDFTEX\ development up to version \currentpdftex. Main text updates
-were done regarding the new configuration scheme, font mapping, and new
-or updated primitives. The primary repository for the manual and its
-sources is at \from[ptex_devel]. Copies in \PDF\ format can also be
-found on \CTAN\ in \from[ptex_ctan].
+This manual revision (\rcsrevision) is intended to track current
+\PDFTEX\ development, up to version \currentpdftex. The primary
+repository for the manual and its sources is at \from[ptex_devel].
+Copies in \PDF\ format can also be found on \CTAN\ in \from[ptex_ctan].
Thanks to the many people who have contributed to the manual.
New errors might have slipped in afterwards by the editor.
@@ -710,7 +697,7 @@ Please send questions or suggestions by email to \from[ptex_bugs].
\subsection{Legal Notice}
-Copyright \copyright\ 1996||2010 \THANH.
+Copyright \copyright\ 1996||2014 \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;
@@ -879,14 +866,14 @@ is \WEBC||specific.
\subsection{Getting sources and binaries}
-The latest sources of \PDFTEX\ are currently distributed for compilation
+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].
The \PDFTEX\ sources can also be found at their canonical place in the
-\CTAN\ network, \from[ptex_ctan]. Separate \PDFTEX\ binaries for
-various systems might also be available, check out the subdirectories
+\CTAN\ network, \from[ptex_ctan]. Precompiled \PDFTEX\ binaries for
+various systems might also be available, check the subdirectories
below \from[ctan_systems].
%***********************************************************************
@@ -902,37 +889,38 @@ needed to compile \PDFTEX:
\startesctyping
cd $HOME/pdftex
unzip pdftex-@currentpdftex.zip
-cd pdftex-@currentpdftex
-./build.sh
+cd pdftex-@currentpdftex/source
+./build-pdftex.sh
\stopesctyping
The binary \filename{pdftex} is then built in the subdirectory
-\filename{build/texk/web2c}. In the same directory also the corresponding
-pool file \filename{pdftex.pool} is generated; it's needed for creating
-the format files.
+\filename{build/texk/web2c}.
The obsolescent binary \filename{pdfetex} is still generated for backward
compatibility, but since version 1.40 it is just a file copy
of the file \filename{pdftex}.
-Together with the \filename{pdftex} binary also the \filename{pdftosrc}
-and \filename{ttf2afm} binaries are generated.
+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 and the
-pool file \filename{pdftex.pool} into their proper places within
-the \TDS\ structure of the \TEX\ system. Put the binary files
-into the binary directory (\eg\ for a typical \TEXLIVE\ system)
-\filename{/usr/local/texlive/2010/bin/x86_64-linux}, and the pool file
-into \filename{/usr/local/texlive/2010/texmf/web2c}.
+\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}.
-Don't forget to do a \filename{texconfig-sys init} afterwards, so that
-all formats are regenerated system-wide with the fresh \filename{pdftex}
-binary.
+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.
%***********************************************************************
@@ -942,7 +930,7 @@ binary.
configuration file called \filename {texmf.cnf}. The location
of this file is the appropriate position within the \TDS\ tree
relative to the place of the \PDFTEX\ binary; on a \TEXLIVE\ system,
-file \filename{texmf.cnf} typically is located either in directory
+\filename{texmf.cnf} is typically located either in directory
\filename{texmf/web2c} or \filename{texmf-local/web2c}. The path to
file \filename{texmf.cnf} can also be set up by the environment variable
\type{TEXMFCNF}.
@@ -963,12 +951,12 @@ where the various bits and pieces are going.
\NC output files \NC \type{TEXMFOUTPUT} \NC\NR
\NC input files, images \NC \type{TEXINPUTS} \NC\NR
\NC format files \NC \type{TEXFORMATS} \NC\NR
-\NC text pool files \NC \type{TEXPOOL} \NC\NR
+\NC \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 type1 fonts \NC \type{T1FONTS} \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 pixel fonts \NC \type{PKFONTS} \NC\NR
@@ -995,7 +983,9 @@ input files and searched for along this path.
\PathDescription {TEXFORMATS} Search path for format (\type{.fmt}) files.
-\PathDescription {TEXPOOL} Search path for pool (\type{.pool}) files.
+\PathDescription {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.
@@ -1117,23 +1107,35 @@ even without setting any parameters.
% Set pdfTeX parameters for pdf mode (replacing pdftex.cfg file).
% Thomas Esser, 2004. public domain.
\pdfoutput=1
+\pdfcompresslevel=9
+\pdfdecimaldigits=3
\pdfpagewidth=210 true mm
\pdfpageheight=297 true mm
+\pdfhorigin=1 true in
+\pdfvorigin=1 true in
\pdfpkresolution=600
+%
+% As of TeX Live 2010, we output PDF 1.5 by default, so we can enable
+% more compression. To change this for the installation, comment out or
+% delete these lines and remake the formats. To change it for a
+% particular LaTeX document, \RequirePackage{pdf14} early.
+%
+\pdfminorversion=5
+\pdfobjcompresslevel=2
\endinput
\stoptyping
\stopframedtext
\stopbuffer
\placefigure[here][in:pdftexconfig]
- {A typical configuration file (\filename{pdftexconfig.tex}).}
+ {The \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\ pool and hash size), and other general parameters.
+memory layout (\eg\ string pool and hash size), and other general parameters.
%***********************************************************************
@@ -1246,7 +1248,7 @@ for an English format, or
texexec --make en de
\stoptyping
-for an English and German one. Most users will simply say:
+for an English and German one. Most \CONTEXT\ users will simply say:
\starttyping
texexec --make --all [--alone]
@@ -1289,23 +1291,6 @@ getting started:
\startitemize
-\head \type{I can't read pdftex.pool; bad path?}
-
- \type{TEXMFCNF} is not set correctly and so \PDFTEX\ cannot find
- \type{texmf.cnf}, or \type{TEXPOOL} in \filename {texmf.cnf}
- doesn't contain a path to the pool file \filename {pdftex.pool}.
-
-\head \type{You have to increase POOLSIZE.}
-
- \PDFTEX\ cannot find \filename {texmf.cnf}, or the value of \type
- {pool_size} specified in \filename {texmf.cnf} is not large enough
- and must be increased. If \type{pool_size} is not specified in
- \filename {texmf.cnf} then you can add something like
-
-\starttyping
-pool_size=500000
-\stoptyping
-
\head \type{I can't find the format file `pdftex.fmt'!} \crlf
\type{I can't find the format file `pdflatex.fmt'!}
@@ -1318,24 +1303,8 @@ pool_size=500000
\type{Fatal format file error; I'm stymied}
This appears \eg\ if you forgot to regenerate the \type{.fmt}
- files after installing a new version of the \PDFTEX\ binary and
- \filename {pdftex.pool}. The first line tells by which engine
- the offending format was generated.
-
-\head \type{TEX.POOL doesn't match; TANGLE me again!} \crlf
- \type{TEX.POOL doesn't match; TANGLE me again (or fix the path).}
-
- This might appear if you forgot to install the proper \filename
- {pdftex.pool} when installing a new version of the \PDFTEX\
- binary. \Eg\ under \TEXLIVE\ then run \type{texconfig-sys init}
- as root.
-
-%\head \type{! I can't find file `*pdftex.ini'.} \crlf
-% \type{<*> *pdftex.ini}
-%
-% This typically appears when you try to generate an extended format
-% with the \PDFTEX\ engine (it does not know about the special asterisk
-% \type{*} notation). Use the \PDFETEX\ engine instead.
+ 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,
@@ -1370,7 +1339,7 @@ a postprocessor, macro packages that take care of these \PDF\ features
have to be set up properly. Typical tasks are handling color,
graphics, hyperlink support, threading, font||inclusion, as well as
page imposition and manipulation. All these \PDF||specific tasks can be
-commanded by \PDFTEX's own primitives (a few also by a \PDFTEX||specific
+controlled by \PDFTEX's own primitives (a few also by a \PDFTEX||specific
\type{\special{pdf: ...}} primitive). Any other \type{\special{}} commands,
like the ones defined for various \DVI\ postprocessors, are simply
ignored by \PDFTEX\ when in \PDF\ output mode; a warning is given only
@@ -1484,7 +1453,6 @@ and {\em fontfile}, however the first three fields must be given in
fixed order.
\startdescription {tfmname}
-
sets the name of the \TFM\ file for a font --- the name \TEX\ sees.
This name must always
be given.
@@ -1492,7 +1460,6 @@ be given.
\stopdescription
\startdescription {basename}
-
sets the (\POSTSCRIPT) base font name, which has two uses:
First, when a \PDF\ file is embedded by \type{\pdfximage}, the
@@ -1505,8 +1472,8 @@ mentioned in the map line (see {\em fontfile} below). By this collecting
mechanism Type~1 glyphs can be shared between several embedded \PDF\
files and with text that is typeset by \PDFTEX, which helps keeping the
resulting \PDF\ file size small, if many files with similar Type~1(C)
-fonts are embedded. Replacing Type1 fonts from embedded \PDF\ files
-requires that also a Type1 font file name is in the {\em fontfile} field
+fonts are embedded. Replacing Type~1 fonts from embedded \PDF\ files
+requires that also a Type~1 font file name is in the {\em fontfile} field
(see below).
Second, if a font file is not to be embedded into the \PDF\ output
@@ -1521,7 +1488,6 @@ strictly speaking it's optional).
\stopdescription
\startdescription {fontflags}
-
specify some characteristics of the font. The following description of
these flags is taken, with slight modification, from the \PDFReference\
(the section on font descriptor flags). Viewers can adapt their rendering
@@ -1593,15 +1559,14 @@ features of bold characters may be thickened at small text sizes.
If the {\em fontflags} field is not given, \PDFTEX\ treats it as being~4,
a symbolic font. If you do not know the correct value, it is best not
to specify it at all, as specifying a bad value of font flags may cause
-troubles in viewers. On the other hand this option is not absolutely
+trouble in viewers. On the other hand this option is not absolutely
useless because it provides backward compatibility with older map files
(see the {\em fontfile} description below).
\stopdescription
\startdescription {special}
-
-instructions can be used to manipulate fonts similar to the way
+specifies instructions to manipulate fonts similar to the way
\type{dvips} does. Currently only the keywords \type{SlantFont}
and \type{ExtendFont} are interpreted, other instructions (as
\type{ReEncodeFont} with parameters, see {\em encoding} below) are
@@ -1612,7 +1577,6 @@ instruction must be enclosed by double quotes \type{"}.
\stopdescription
\startdescription {encodingfile}
-
specifies the name of the file containing the external encoding vector
to be used for the font. The encoding file must have name extension
\type{.enc}, and the full file name including this extension must be given
@@ -1626,7 +1590,6 @@ and it is {\em required} when subsetting a TrueType font.
\stopdescription
\startdescription {fontfile}
-
sets the name of the font file to be embedded into the \PDF\ output for a
given \TeX\ font (the {\em tfmname}~$\longleftrightarrow$~{\em fontfile}
mapping is the most prominent use of the \filename{pdftex.map} file).
@@ -1656,7 +1619,7 @@ which tells how to handle the font file:
are embedded, including even the ones that are not used in the
document. Apart from causing large size \PDF\ output, this option
may cause troubles with TrueType fonts, so it is normally not
- recommended for Type1 or TrueType fonts. But this is currently
+ recommended for Type~1 or TrueType fonts. But this is currently
the only mode that allows the use of OpenType fonts. This mode
might also be useful in case the font is atypical and can not be
subsetted well by \PDFTEX. {\em Beware: some font vendors forbid
@@ -1741,7 +1704,7 @@ cmr10 CMR10 <cmr10.pfb
\stoptyping
A SlantFont is specified similarly as for \type{dvips}. The \type
-{SlantFont} or \type{ExtendFont} entries work only with embedded Type1
+{SlantFont} or \type{ExtendFont} entries work only with embedded Type~1
fonts:
\starttyping
@@ -1854,7 +1817,7 @@ new Didot (1\,nd~=~0.375\,mm) and the new Cicero (1\,nc~=~12\,nd)
%%S pdfTeX documentation file pdftex-t.tex by script syntaxform.awk.
%%S Used convention for syntax rules is borrowed from `TeXbook naruby'
%%S by Petr Olsak.
-%%S $Id: pdftex-t.tex 655 2010-11-23 00:37:25Z karl $
+%%S $Id: pdftex-t.tex 711 2014-04-23 22:56:07Z karl $
%%S NL
%%S integer registers:
@@ -2007,6 +1970,18 @@ new Didot (1\,nd~=~0.375\,mm) and the new Cicero (1\,nc~=~12\,nd)
\Tex {\pdfdraftmode} \Whatever{integer}
}
+\Syntax {
+\Tex {\pdfsuppresswarningdupdest} \Whatever{integer}
+}
+
+\Syntax {
+\Tex {\pdfsuppresswarningdupmap} \Whatever{integer}
+}
+
+\Syntax {
+\Tex {\pdfsuppresswarningpagegroup} \Whatever{integer}
+}
+
\stoppacked
%%S NL
@@ -2798,7 +2773,7 @@ producing files with \PDF\ version 1.5. If specified, this primitive must
appear before any data is to be written to the generated \PDF\ file, so you
should put it at the very start of your files. The command has been introduced
in \PDFTEX\ 1.30.0 as a shortened synonym of \type{\pdfoptionpdfminorversion}
-command, that is obsolete by now.
+command, which is now obsolete.
Distributions alter the default value here; for example, \TEXLIVE\ 2010
sets \type{\pdfminorversion=5} when its formats are built, so object
@@ -3088,7 +3063,7 @@ ignored), as \PDFTEX\ generates expanded copies of the unexpanded \TFM\
data structures and keeps them in its memory. Since \PDFTEX~1.40.0 the
\type{autoexpand} mode happens within the page stream by modification of
the text matrix (\PDF\ operator ``\type{Tm}''), and not anymore on font
-file level, giving the advantage that it now works not only with Type1
+file level, giving the advantage that it now works not only with Type~1
but also with TrueType and OpenType fonts (and even without embedding
a font file; but that's not recommended). In this mode \PDFTEX\ requires
only unexpanded font files.
@@ -3250,7 +3225,7 @@ list). These \type{\unhbox} or \type{\unhcopy} are often used together
with \type{\vsplit} for dis- and re||assembling of paragraphs, \eg\ to
add line numbers. Paragraphs treated like this do not show character
protrusion by default, as the margin kerns have been removed during the
-unpackaging process.
+unpacking process.
The \type{\leftmarginkern} and \type{\rightmarginkern} primitives allow
to access the margin kerns and store them away before unpackaging the
@@ -3308,7 +3283,8 @@ This primitive defines \Something{control sequence} as a synonym for
This primitive inserts the \Something{general text} to the \type {/Font}
dictionary. The text must conform to the specifications as laid down in
-the \PDFReference, otherwise the document can be invalid.
+the \PDFReference, otherwise the document can be invalid. For examples,
+see the \type{cmap} and \type{CJK} packages.
\pdftexprimitive {\Syntax {\Tex {\pdffontname} \Something{font} \Whatever
{expandable}}}
@@ -3458,6 +3434,7 @@ token list for the \type{-ini} run, \eg:
This would always read the file \type{myspecial.map} after the default
\type{pdftex.map} file.
+
\pdftexprimitive {\Syntax {\Tex {\pdfmapline} \Something{map spec}}}
\bookmark{\tex{pdfmapline}}
@@ -3479,6 +3456,20 @@ before finally putting it into a map file.
of the default map file, if it comes early enough in the \TeX\
input. \introduced{1.20a}
+
+\pdftexprimitive {\Syntax {\Tex {\pdfsuppresswarningdupmap}
+\Whatever{integer}}}
+
+\bookmark{\tex{pdfsuppresswarningdupmap}}
+
+Ordinarily, \PDFTEX\ gives a warning when a duplicate map entry for a
+given font is read, whatever the mechanism. However, sometimes it is
+useful to include map information within the document, using
+\type{\pdfmapfile} or \type{\pdfmapline}, even for fonts that happen to
+be installed on the system. Then seeing the warnings on every run is
+just noise, and can be suppressed by setting this parameter to a
+positive number. \introduced{1.40.13}
+
\pdftexprimitive {\Syntax {\Tex {\pdftracingfonts} \Whatever{integer}}}
\bookmark{\tex{pdftracingfonts}}
@@ -3549,12 +3540,21 @@ value is \type{no_tag}, \type{1} if \type{lig_tag} is set, \type{2} if
\pdftexprimitive {\Syntax {\Tex {\pdfgentounicode} \Whatever{integer}}}
-If set to \type{1} when the job ends, a mapping from glyph names to
-Unicode characters will be created for the fonts used in the documents
-(such a mapping is called a CMap), to allow \PDF\ readers to extract
-text content (e.g. for searching). Most fonts use standard names for
-characters, so the mapping is generally automatic and shouldn't be set
-manually. Otherwise, the following command must be used.
+By default, \PDFTEX\ does not include a \type{/ToUnicode} resource when
+including fonts in the output. Such a resource (also called a CMap
+resource) maps glyph names to Unicode characters in a \PDF\ file.
+Lacking such a resource, it is the \PDF\ reader which determines how and
+whether searching in the \PDF\ file works. In practice, searching for
+basic ASCII characters generally works, but searching for anything
+beyond those, including ligatures such as `fi', fails in some versions
+of some PDF browsers (most notably Adobe Reader).
+
+If \type{\pdfgentounicode} is set to \type{1} when the job ends, the
+\type{/ToUnicode} resource will be included in the output, with mappings
+for Type~1 fonts used in the documents. The mapping is created as
+follows: for each glyph in the font, look for its \type{ToUnicode} value
+in a global hash table. By default that global hash table is empty;
+entries are added to the table using the following command:
\pdftexprimitive {\Syntax {\Tex {\pdfglyphtounicode} \Something{general text} \Something{general text}}}
@@ -3563,12 +3563,81 @@ numeric values denoting characters. For instance:
\starttyping
\pdfgentounicode=1
-\pdfglyphtounicode{ff}{0066066}
+\pdfglyphtounicode{ff}{0066 0066}
\stoptyping
\noindent maps the \type{ff} ligature to a pair of \type{f}'s (whose
code is \type{U+0066}).
+The \type{glyphtounicode.tex} file (distributed with \PDFTEX\ and other
+software) contains thousands of such definitions, covering most common
+glyph names. So, for practical purposes, one would probably want:
+
+\starttyping
+\input glyphtounicode
+\pdfgentounicode=1
+\stoptyping
+
+\LATEX\ users could load the \type{cmap} package to achieve the same
+effect.
+
+
+\pdftexprimitive {\Syntax {\Tex {\pdfnobuiltintounicode} \Something{font}}}
+
+The primary purpose of this command is to prevent \PDFTEX\ from
+generating the \type{ToUnicode}/CMap resource for the given font when
+\type{\pdfgentounicode=1}, most likely because the CMap resource is
+already generated by some other method (for example, the \LATEX\
+\type{cmap} package uses \type{\pdffontattr} to generate a CMap
+resource).
+
+Minimal example:
+\starttyping
+\font\f=cmb10
+\pdfnobuiltintounicode\f
+\f No unicode mappings for this output.
+\stoptyping
+\introduced{1.40.11}
+
+
+\pdftexprimitive {\Syntax {\Tex {\pdfinterwordspaceon} \Whatever{integer}}}
+\pdftexprimitive {\Syntax {\Tex {\pdfinterwordspaceoff} \Whatever{integer}}}
+
+These commands create corresponding whatsit nodes which turn on/off
+generation of faked interword spaces in the output. This allows for
+better reflowing of text on the fly by \PDF\ readers, better extraction
+of textual content, and is required by \PDF/A. It does not affect the
+normal \TeX\ justification with glue.
+
+This requires finding and reading font files \type{dummy-space.tfm} and
+\type{pfb}; the font is included in the \PDF\ output and character 32 is
+inserted from it as the ``fake'' space.
+
+Example of usage:
+
+\starttyping
+Text with no interword spaces.
+
+\pdfinterwordspaceon
+
+Switch to text with faked interword spaces.
+
+\pdfinterwordspaceoff
+
+Back to text with no interword spaces.
+\stoptyping
+\introduced{1.40.15}
+
+\pdftexprimitive {\Syntax {\Tex {\pdffakespace}}}
+
+Insert a faked interword space to the output, regardless of the value of
+\type{\pdfinterwordspaceon} and \type{\pdfinterwordspaceoff}. Example:
+
+\starttyping
+Text with no interword \pdffakespace\pdffakespace spaces.
+\stoptyping
+\introduced{1.40.15}
+
%***********************************************************************
\subsection{Spacing}
@@ -3623,7 +3692,7 @@ If positive, automatic insertion of kerns before characters is enabled.
The width of the kern, in thousandths of an em, inserted before a character.
It is clipped to the range \type{-1000}||\type{1000}. For instance, with the
following code, a .15\,em-kern will be inserted before all question marks
-(useful for e.g. French punctuation):
+(useful for \eg\ French punctuation):
\starttyping
\pdfprependkern=1
@@ -4069,7 +4138,7 @@ This controls the behaviour of \PDFTEX\ when a \PDF\ file is included
that has a newer version than the one specified by this primitive: If it
is set to~0, \PDFTEX\ gives only a warning; if it's~1, \PDFTEX\ raises
an error. The command has been introduced in \PDFTEX\ 1.30.0 as
-a shortened synonym of \type{\pdfoptionpdfinclusionerrorlevel}, that is
+a shortened synonym of \type{\pdfoptionpdfinclusionerrorlevel}, which is
now obsolete.
\pdftexprimitive {\Syntax {\Tex {\pdfimagehicolor} \Whatever{integer}}}
@@ -4173,6 +4242,23 @@ disk. Bigger files might be created, but included \PDF\ files are sure to
be embedded with the adequate fonts; indeed, the fonts on disk might be
different from the embedded ones, and glyphs might be missing.
+\pdftexprimitive {\Syntax {\Tex {\pdfsuppresswarningpagegroup}
+\Whatever{integer}}}
+
+\bookmark{\tex{pdfsuppresswarningpagegroup}}
+
+Ordinarily, \PDFTEX\ gives a warning when more than one included \PDF\
+file has a so-called ``page group object'' (\type{/Group}), because only
+one can ``win'' --- that is, be propagated to the page level. Usually
+the page groups are identical, but when they are not, the result is
+unpredictable. It would be ideal if \PDFTEX\ in fact detected whether
+the page groups were the same and only gave the warning in the
+problematic case; unfortunately, this is not easy (a patch would be
+welcome). Nevertheless, often one observes that there is no actual
+problem. Then seeing the warnings on every run is just noise, and can
+be suppressed by setting this parameter to a positive number.
+\introduced{1.40.14}
+
%***********************************************************************
\subsection{Annotations}
@@ -4348,6 +4434,18 @@ a hyperlink and is read when a page containing hyperlinks is shipped out.
Margin added to the dimensions of the rectangle around the destinations.
+\pdftexprimitive {\Syntax {\Tex {\pdfsuppresswarningdupdest}
+\Whatever{integer}}}
+
+\bookmark{\tex{pdfsuppresswarningdupdest}}
+
+Ordinarily, \PDFTEX\ gives a warning when the same destination is used
+more than once. However, due to problematic macro packages, sometimes a
+document may end up producing the warning through no fault of its own,
+and fixing the macros may well not be trivial. Then seeing the warnings
+on every run is just noise, and can be suppressed by setting this
+parameter to a positive number. \introduced{1.40.13}
+
%***********************************************************************
\subsection{Bookmarks}
@@ -4573,54 +4671,56 @@ hexadecimal format (same as \type{\pdfescapehex}).
\bookmark{\tex{ifpdfabsnum}}
-This primitive works like the standard \type{\ifnum} condition check,
-except that it compares absolute values of numbers. Although it seems to
-be a trivial shortcut for a couple of \type{\ifnum x<0} tests, as a
-primitive it is more friendly in usage and works a bit faster.
+This conditional works like the standard \type{\ifnum}, except that it
+compares absolute values of numbers. Although it seems to be a trivial
+shortcut for a couple of \type{\ifnum x<0} tests, as a primitive it is
+considerably more friendly in usage and works a bit faster.
\introduced{1.40.0}
\pdftexprimitive{\Syntax {\Tex {\ifpdfabsdim} \Whatever{expandable}}}
\bookmark{\tex{ifpdfabsdim}}
-Like \type{\ifpdfabsnum}, the primitive works as normal \type{\ifdim} condition check, except
-that it compares absolute values of dimensions. \introduced{1.40.0}
+Analogous to \type{\ifpdfabsnum}, this conditional works like
+\type{\ifdim}, except that it compares absolute values of
+dimensions. \introduced{1.40.0}
\pdftexprimitive{\Syntax {\Tex {\pdfuniformdeviate} \Something{number} \Whatever{expandable}}}
\bookmark{\tex{pdfuniformdeviate}}
-The commands generates a uniformly distributed random integer value between
-0 (inclusive) and \Something{number} (exclusive). This primitive expands to
-a list of tokens. \introduced{1.30.0}
+Generate a uniformly-distributed random integer value between 0
+(inclusive) and \Something{number} (exclusive). This primitive expands
+to a list of tokens. \introduced{1.30.0}
\pdftexprimitive{\Syntax {\Tex {\pdfnormaldeviate} \Whatever{expandable}}}
\bookmark{\tex{pdfnormaldeviate}}
-%MS Hopefully the random number doesn't influce the length of this paragraph;
-%MS otherwise texexec could loop :-)
-The commands generates a random integer value with a mean of 0 and a unit
-of 65\,536, \eg\ $\pdfnormaldeviate$. This primitive expands to a list of
-tokens. \introduced{1.30.0}
+Generate a normally-distributed random integer with a mean of~0 and
+standard deviation 65\,536. That is, about 68\% of the time, the result
+will be between $-65536$ and $65536$ (one standard deviation away from
+the mean). About 95\% of results will be within two standard
+deviations, and 99.7\% within three. This primitive expands to a list
+of tokens. \introduced{1.30.0}
\pdftexprimitive {\Syntax {\Tex {\pdfrandomseed}} \Whatever{read||only
integer}}
\bookmark{\tex{pdfrandomseed}}
-You can use \type{\the\pdfrandomseed} to query the current seed value, so
-you can \eg\ write the value to the log file.
-The initial value of the seed is derived from the system time, and is not
-more than 1\,000\,999\,999 (this ensures that the value can be used with
-commands like \type{\count}). \introduced{1.30.0}
+You can use \type{\the\pdfrandomseed} to query the current seed value,
+so you can \eg\ write the value to the log file. The initial value of
+the seed is derived from the system time, and is not more than
+1\,000\,999\,999 (this ensures that the value can be used with commands
+like \type{\count}). \introduced{1.30.0}
\pdftexprimitive{\Syntax {\Tex {\pdfsetrandomseed} \Something{number}}}
\bookmark{\tex{pdfsetrandomseed}}
-This sets the random seed (\type{\pdfrandomseed}) to a specific value,
-allowing you to re-play sequences of semi-randoms at a later moment.
+Set the random seed (\type{\pdfrandomseed}) to a specific value,
+allowing you to replay sequences of semi-randoms at a later moment.
\introduced{1.30.0}
%***********************************************************************
@@ -4632,19 +4732,19 @@ integer}}
\bookmark{\tex{pdfelapsedtime}}
-The command returns a number that represents the time elapsed from the
-moment of run start. The elapsed time is returned in `scaled seconds', that
-means seconds divided by 65536, \eg\ \PDFTEX\ has run for \the\pdfelapsedtime\
-`scaled seconds' when this paragraph was typeset. Obviously, the command will
-never return a value greater than the highest number available in \TeX: if
-the time exceeds 32767 seconds, the constant value $2^{31}-1$ will be returned.
-\introduced{1.30.0}
+Return a number that represents the time elapsed from the moment of the
+start of the run. The elapsed time is returned in `scaled seconds',
+meaning seconds divided by 65536, \eg\ \PDFTEX\ has run for
+\the\pdfelapsedtime\ `scaled seconds' when this paragraph was
+typeset. Of course, the command will never return a value greater than
+the highest number available in \TeX: if the time exceeds 32767 seconds,
+the constant value $2^{31}-1$ will be returned. \introduced{1.30.0}
\pdftexprimitive{\type{\pdfresettimer}}
\bookmark{\tex{pdfresettimer}}
-The command resets the internal timer so that \type{\pdfelapsedtime}
+Reset the internal timer so that \type{\pdfelapsedtime}
starts returning micro||time from~0 again. \introduced{1.30.0}
%***********************************************************************
@@ -4804,7 +4904,7 @@ 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, e.g. just to get the \BIBTEX\ references
+don't care about the output, \eg\ just to get the \BIBTEX\ references
right. \introduced{1.40.0}
@@ -5185,7 +5285,7 @@ the \PDFReference. The following key ends up in the document catalog.
produced the file as displayed by \typ {pdftex --version}, \eg\
{\tt\pdftexbanner}. This is necessary because the string in the
\type {Producer} key in the info dictionary is rather short,
-\eg\ {\tt pdfTeX-\currentpdftex}. \NC \NR
+namely {\tt pdfTeX-\currentpdftex}. \NC \NR
\HL
\stoptabulate
@@ -5650,4 +5750,7 @@ as a draft) by the Free Software Foundation.
%D And then we're done.
+% Evidently ConTeXt somewhere sets \pdfgentounicode=1. Or something.
+% So insert the mappings. Seems like a good thing anyway.
+\input glyphtounicode
\stoptext