diff options
Diffstat (limited to 'systems/doc/pdftex')
| -rw-r--r-- | systems/doc/pdftex/manual/ChangeLog | 30 | ||||
| -rw-r--r-- | systems/doc/pdftex/manual/Makefile | 5 | ||||
| -rw-r--r-- | systems/doc/pdftex/manual/pdftex-a.pdf | bin | 1002639 -> 1007743 bytes | |||
| -rw-r--r-- | systems/doc/pdftex/manual/pdftex-syntax.txt | 551 | ||||
| -rw-r--r-- | systems/doc/pdftex/manual/pdftex-t.tex | 255 |
5 files changed, 753 insertions, 88 deletions
diff --git a/systems/doc/pdftex/manual/ChangeLog b/systems/doc/pdftex/manual/ChangeLog index 70cf61a930..af506f2082 100644 --- a/systems/doc/pdftex/manual/ChangeLog +++ b/systems/doc/pdftex/manual/ChangeLog @@ -1,3 +1,33 @@ +2023-02-26 Karl Berry <karl@freefriends.org> + + * pdftex-t.tex (\introducedplural): new macro. + (\pdfinterwordspaceon,off, \pdfspacefont): tweak Thanh's description. + Use \Lbrace, \Rbrace outside of \type. + +2023-01-20 Karl Berry <karl@freefriends.org> + + * pdftex-t.tex (\pdfliteral, \special): document new shipout keyword. + From Phelype Oleinik <phe.h.o1@gmail.com>, 16 Jan 2023 20:51:33, + mail to latex-team + karl. + +2022-12-22 Karl Berry <karl@freefriends.org> + + * pdftex-t.tex (\pdfomitprocset): document. + +2022-06-08 Karl Berry <karl@freefriends.org> + + * pdftex-t.tex (Graphics): never mind about "encapsulated PDF"; + mention supp-pdf.tex and supp-pdf.mkii. + +2022-04-26 Karl Berry <karl@freefriends.org> + + * pdftex-t.tex (\pdfinfoomitdict): document. + + * pdfhelp-help.txt: regenerate for mailing list url. + + * Makefile (pdftex-w.pdf): set KPATHSEA_WARNING=0 since we run + this with -ini. + 2022-02-28 Karl Berry <karl@freefriends.org> * pdftex-t.tex (ptex_devel): svn://tug.org url. diff --git a/systems/doc/pdftex/manual/Makefile b/systems/doc/pdftex/manual/Makefile index adbb1c7c95..481b8567b9 100644 --- a/systems/doc/pdftex/manual/Makefile +++ b/systems/doc/pdftex/manual/Makefile @@ -1,4 +1,4 @@ -# $Id: Makefile 875 2022-03-01 02:08:10Z karl $ +# $Id: Makefile 879 2022-04-26 16:19:17Z karl $ # Makefile for pdfTeX documentation. Public domain. # Get version we're documenting from the \def in the manual. @@ -60,6 +60,7 @@ pdftex-w.txt: pdftex-w.pdf pdftex_binary = ../../source/build-pdftex/texk/web2c/pdftex pdftex-w.pdf: pdftex-w.tex Makefile TEXFONTS=/usr/local/texlive/dev/texmf-dist/fonts// \ + KPATHSEA_WARNING=0 \ $(pdftex_binary) -ini '$<' @@ -68,7 +69,7 @@ pdftex-help.txt: force $(pdftex_binary) --help >$@ || rm -f $@ force: -# if we don't have a build tree around, just try from the path. +# if we don't have a build tree around, try from PATH. build_binary := ../../source/build-pdftex/texk/web2c/pdftex ifneq "$(realpath $(build_binary))" "" pdftex_binary := $(build_binary) diff --git a/systems/doc/pdftex/manual/pdftex-a.pdf b/systems/doc/pdftex/manual/pdftex-a.pdf Binary files differindex 4fa8985b52..6a03bc138c 100644 --- a/systems/doc/pdftex/manual/pdftex-a.pdf +++ b/systems/doc/pdftex/manual/pdftex-a.pdf diff --git a/systems/doc/pdftex/manual/pdftex-syntax.txt b/systems/doc/pdftex/manual/pdftex-syntax.txt index 31b92f29e9..6e8a42a305 100644 --- a/systems/doc/pdftex/manual/pdftex-syntax.txt +++ b/systems/doc/pdftex/manual/pdftex-syntax.txt @@ -27,10 +27,12 @@ \pdfinclusioncopyfonts (integer) \pdfinclusionerrorlevel (integer) \pdfinfoomitdate (integer) +\pdfinfoomitdict (integer) \pdfmajorversion (integer) \pdfminorversion (integer) \pdfobjcompresslevel (integer) \pdfomitcharset (integer) +\pdfomitprocset (integer) \pdfoutput (integer) \pdfpagebox (integer) \pdfpkresolution (integer) @@ -139,7 +141,7 @@ \pdfinfo <general text> \pdfinterwordspaceoff \pdfinterwordspaceon -\pdfliteral [<pdfliteral spec>] <general text> (h, v, m) +\pdfliteral [shipout] [direct | page] <general text> (h, v, m) \pdfmapfile <map spec> \pdfmapline <map spec> \pdfnames <general text> @@ -159,6 +161,7 @@ \pdfsavepos (h, v, m) \pdfsetmatrix \pdfsetrandomseed <number> +\pdfspacefont <general text> \pdfstartlink [<rule spec>] [<attr spec>] <action spec> (h, m) \pdfthread [<rule spec>] [<attr spec>] <id spec> (h, v, m) \pdftrailer <general text> @@ -170,6 +173,7 @@ \special {pdf: <text> } \special {pdf:direct: <text> } \special {pdf:page: <text> } +\special [shipout] {<general text> } \vadjust [<pre spec>] <filler> { <vertical mode material> } (h, m) %% Syntax rules: @@ -225,7 +229,6 @@ <shrink> --> <number> <step> --> <number> <pre spec> --> pre -<pdfliteral spec> --> direct | page <pdfspecial spec> --> { [<pdfspecial id> [<pdfspecial modifier>]] <balanced text> } <pdfspecial id> --> pdf: | PDF: <pdfspecial modifier> --> direct: @@ -235,3 +238,547 @@ | [<file spec>] [<goto-action struct spec>] [<page spec>] <general text> | <file spec> [<goto-action struct spec>] <nameid> <newwindow spec> | <file spec> [<goto-action struct spec>] [<page spec>] <general text> <newwindow spec> +<text> }} is equivalent to \Syntax{\pdfliteral +shipout { <text> }}. +================= ERROR +%*********************************************************************** +================= ERROR +\subsection{Strings} +================= ERROR +\pdftexprimitive{\Syntax{\pdfescapestring <general text> + (expandable)}} +\bookmark{\pdfescapestring} +================= ERROR +Starting with version 1.30.0, \PDFTEX\ provides a mechanism for converting +a general text into \PDF\ string. Many characters that may be needed inside +such a text (especially parenthesis), have a special meaning inside a \PDF\ +string object and thus, can't be used literally. The primitive replaces each +special \PDF\ character by its literal representation by inserting a backslash +before that character. Some characters (\eg\ space) are also converted into +3-digit octal number. In example, \type{\pdfescapestring{Text (1)}} will be +expanded to \type{Text\040\(1\)}. This ensures a literal interpretation of the +text by the \PDF\ viewer. +\introduced{1.30.0} +================= ERROR +\pdftexprimitive{\Syntax{\pdfescapename <general text> + (expandable)}} +\bookmark{\pdfescapename} +================= ERROR +In analogy to \type{\pdfescapestring}, \type{\pdfescapename} replaces each +special \PDF\ character inside the general text by its hexadecimal +representation preceded by \type{#} character. This ensures the proper +interpretation of the text if used as a \PDF\ name object. In example, +\type{Text (1)} will be replaced by \type{Text#20#281#29}. +\introduced{1.30.0} +================= ERROR +\pdftexprimitive{\Syntax{\pdfescapehex <general text> + (expandable)}} +\bookmark{\pdfescapehex} +================= ERROR +This command converts each character of <general text> into its +hexadecimal representation. Each character of the argument becomes a pair of +hexadecimal digits. \introduced{1.30.0} +================= ERROR +\pdftexprimitive{\Syntax{\pdfunescapehex <general text> + (expandable)}} +\bookmark{\pdfunescapehex} +================= ERROR +This command treats each character pair of <general text> as +a hexadecimal number and returns an \ASCII\ character of this code. +\introduced{1.30.0} +================= ERROR +\pdftexprimitive{\Syntax{\pdfstrcmp <general text> + <general text> (expandable)}} +\bookmark{\pdfstrcmp} +================= ERROR +This command compares two strings and expands to \type{0} if the strings +are equal, to \type{-1} if the first string ranks before the second, and +to \type{1} otherwise. \introduced{1.30.0} +================= ERROR +\pdftexprimitive{\Syntax{\pdfmatch [icase] + [subcount <integer>] <general text> + <general text> (expandable)}} +\bookmark{\pdfmatch} +================= ERROR +This command implements pattern matching (using the syntax of \POSIX\ +extended regular expressions). The first <general text> is a +pattern and the second is a string. The command expands to \type{-1} if +the pattern is invalid, to \type{0} if no match is found, and to +\type{1} if a match is found. With the \type{icase} option, the matching +is case-insensitive. The \type{subcount} option sets the size of the +table storing the found (sub)patterns; its default is 10. +\introduced{1.30.0} +================= ERROR +\pdftexprimitive{\Syntax{\pdflastmatch <integer> + (expandable)}} +\bookmark{\pdflastmatch} +================= ERROR +The matches found with \type{\pdfmatch} are stored in a table. This +command returns the entry for <integer>, in the format +<position>\type{->}<string>; <position> is +the position of the match (starting at zero) or \type{-1} if no match +was found, and <string> is the matched substring. +================= ERROR +Entry~0 contains the match as a whole; the subsequent entries contain +submatches corresponding to the subpatterns, up to \type{subcount-1}. +================= ERROR +If <integer> is less than zero, an error is given. +================= ERROR +For instance: +================= ERROR +\starttyping +\pdfmatch subcount 3 {ab(cd)*ef(gh)(ij)}{abefghij} +\pdflastmatch0 % "0->abefghij" +\pdflastmatch1 % "-1->" +\pdflastmatch2 % "4->gh" +\pdflastmatch3 % "-1->" +\stoptyping +================= ERROR +Entry~1 is empty because no match was found for \type{cd}, and entry~3 +is empty because it exceeds the table's size as set by \type{subcount}. +\introduced{1.30.0} +================= ERROR +%*********************************************************************** +================= ERROR +\subsection{Numbers} +================= ERROR +\pdftexprimitive{\Syntax{\ifpdfabsnum (expandable)}} +\bookmark{\ifpdfabsnum} +================= ERROR +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} +================= ERROR +\pdftexprimitive{\Syntax{\ifpdfabsdim (expandable)}} +\bookmark{\ifpdfabsdim} +================= ERROR +Analogous to \type{\ifpdfabsnum}, this conditional works like +\type{\ifdim}, except that it compares absolute values of +dimensions. \introduced{1.40.0} +================= ERROR +\pdftexprimitive{\Syntax{\pdfuniformdeviate <number> + (expandable)}} +\bookmark{\pdfuniformdeviate} +================= ERROR +Generate a uniformly-distributed random integer value between 0 +(inclusive) and <number> (exclusive). This primitive expands +to a list of tokens. \introduced{1.30.0} +================= ERROR +\pdftexprimitive{\Syntax{\pdfnormaldeviate (expandable)}} +\bookmark{\pdfnormaldeviate} +================= ERROR +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} +================= ERROR +\pdftexprimitive{\Syntax{\pdfrandomseed (read-only integer)}} +\bookmark{\pdfrandomseed} +================= ERROR +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} +================= ERROR +\pdftexprimitive{\Syntax{\pdfsetrandomseed <number>}} +\bookmark{\pdfsetrandomseed} +================= ERROR +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} +================= ERROR +%*********************************************************************** +================= ERROR +\subsection{Timekeeping} +================= ERROR +\pdftexprimitive{\Syntax{\pdfelapsedtime (read-only integer)}} +\bookmark{\pdfelapsedtime} +================= ERROR +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} +================= ERROR +\pdftexprimitive{\Syntax{\pdfresettimer}} +\bookmark{\pdfresettimer} +================= ERROR +Reset the internal timer so that \type{\pdfelapsedtime} +starts returning micro-time from~0 again. \introduced{1.30.0} +================= ERROR +%*********************************************************************** +================= ERROR +\subsection{Files} +================= ERROR +\pdftexprimitive{\Syntax{\pdffilemoddate <general text> + (expandable)}} +\bookmark{\pdffilemoddate} +================= ERROR +Expands to the modification date of file <general text> in the +same format as for \type{\pdfcreationdate}, \eg\ it's {\tt +\pdffilemoddate {./pdftex-t.tex}} for the source of this manual. As of +version 1.40.20, if the \type{SOURCE_DATE_EPOCH} and +\type{FORCE_SOURCE_DATE} environment variables are both set, +\type{\pdffilemoddate} returns a value in UTC, ending in \type{Z}. +\introduced{1.30.0} +================= ERROR +\pdftexprimitive{\Syntax{\pdffilesize <general text> + (expandable)}} +\bookmark{\pdffilesize} +================= ERROR +Expands to the size of file <general text>, \eg\ it's {\tt +\pdffilesize {./pdftex-t.tex}} for the source of this manual. +\introduced{1.30.0} +================= ERROR +\pdftexprimitive{\Syntax{\pdfmdfivesum + [file] + <general text> (expandable)}} +\bookmark{\pdfmdfivesum\ file} +================= ERROR +If the keyword \type{file} is given, expands to the \MDFIVE\ of file +\Somethingtext{general text} in uppercase hexadecimal format (same as +\type{\pdfescapehex}). Without \type{file}, expands to the \MDFIVE\ of +the \Somethingtext{generaltext} taken as a string. For example, it's +{\tt \pdfmdfivesum file {./pdftex-t.tex}} for the source of this manual. +\introduced{1.30.0} +================= ERROR +\pdftexprimitive{\Syntax{\pdffiledump + [offset <integer>] + [length <integer>] + <general text> (expandable)}} +\bookmark{\pdffiledump} +================= ERROR +Expands to the dump of the first \type{length} \Somethingtext{integer} +bytes of the file \Somethingtext{general text}, in uppercase hexadecimal +format (same as \type{\pdfescapehex}), starting at offset +\type{offset}~\Somethingtext{number}, or the beginning of the file if +\type{offset}. If \type{length} is not given, the default is zero, so +expands to nothing. Both \Somethingtext{integer}s must be $\ge0$. For +example, the first ten bytes of the source of this manual are {\tt +\pdffiledump length 10 {./pdftex-t.tex}}. \introduced{1.30.0} +================= ERROR +\pdftexprimitive{\Syntax{\input <general text> + (expandable)}} +\bookmark{\input} +================= ERROR +As of \TEXLIVE\ 2020, the \type{\input} primitive in all \TEX\ engines, +including \PDFTEX, now also accepts a group-delimited filename argument, +as a system-dependent extension, as in \type{\input} { +\type{foo.tex} }. The usage of \type{\input} with a standard +space/token-delimited filename is completely unchanged. +================= ERROR +This group-delimited argument was previously implemented in Lua\TEX; now +it is available in all engines. \ASCII\ double quote characters +(\type{"}) are removed from the filename, but it is otherwise left +unchanged after tokenization. +================= ERROR +This extension is unlike most others in that it affects a primitive in +standard \TEX\ (\type{\input}), rather than being related to a new +primitive, command line option, etc. This is allowed because additional +methods of recognizing filenames are explicitly mentioned in +\type{tex.web} as acceptable system-dependent extensions. +================= ERROR +Incidentally, this does not directly affect \LATEX's \type{\input} +command, as that is a macro redefinition of the standard \type{\input} +primitive. +================= ERROR +\introduced{1.40.21} +================= ERROR +%*********************************************************************** +================= ERROR +\subsection{Color stack} +================= ERROR +\PDFTEX\ 1.40.0 comes with color stack support (actually any graphic state +stack). +================= ERROR +\pdftexprimitive{\Syntax{\pdfcolorstackinit [page] + [direct] <general text> (expandable)}} +\bookmark{\pdfcolorstackinit} +================= ERROR +The primitive initializes a new graphic stack and returns its number. Optional +page keyword instructs \PDFTEX\ to restore the graphic at the +beginning of every new page. Also optional direct has the same effect +as for \pdfliteral primitive. \introduced{1.40.0} +================= ERROR +\pdftexprimitive{\Syntax{\pdfcolorstack <stack number> + <stack action> <general text>}} +\bookmark{\pdfcolorstack} +================= ERROR +The command operates on the stack of a given number. If \Something{stack +action} is push keyword, the new value provided as +<general text> is inserted into the top of the graphic stack +and becomes the current stack value. If followed by pop, the +top value is removed from the stack and the new top value becomes the +current. set keyword replaces the current value with +<general text> without changing the stack size. +current keyword instructs just to use the current stack value +without modifying the stack at all. \introduced{1.40.0} +================= ERROR +%*********************************************************************** +================= ERROR +\subsection{Transformations} +================= ERROR +Since the content of \pdfliteral is not interpreted anyhow, any +transformation inserted directly into the content stream, as well as saving +and restoring the current transformation matrix, remains unnoticed by +\PDFTEX\ positioning mechanism. As a consequence, links and other annotations +(that are formed in \PDF\ as different layer then the page content) are not +affected by such user-defined transformations. \PDFTEX\ 1.40.0 solves this +problem with three new primitives. +================= ERROR +\pdftexprimitive{\Syntax{\pdfsetmatrix}} +\bookmark{\pdfsetmatrix} +================= ERROR +Afine transformations are normally expressed with six numbers. First +four (no unit) values defining scaling, rotating and skewing, plus two +extra dimensions for shifting. Since the translation is handled by \TeX\ +itself, \pdfsetmatrix primitive expects as an argument a string +containing just the first four numbers of the transformation separated +by a space and assumes two position coordinates to be~0. In example, +\type{\pdfsetmatrix{0.87 -0.5 0.5 0.87}} rotates the current space by 30 +degrees, inserting \type{0.87 -0.5 0.5 0.87 0 0 cm} into the content +stream. \introduced{1.40.0} +================= ERROR +\pdftexprimitive{\Syntax{\pdfsave}} +\bookmark{\pdfsave} +================= ERROR +The command saves the current transformation by inserting \type{q} +operator into the content stream. \introduced{1.40.0} +================= ERROR +\pdftexprimitive{\Syntax{\pdfrestore}} +\bookmark{\pdfrestore} +================= ERROR +The command restores previously saved transformation by inserting \type{Q} +operator into the content stream. One should keep in mind that \pdfsave +and \pdfrestore pairs should always be properly nested and should start +and end at the same group level. \introduced{1.40.0} +================= ERROR +%*********************************************************************** +================= ERROR +\subsection{Macro programming} +================= ERROR +Expansion-related. +================= ERROR +\pdftexprimitive{\Syntax{\expanded <tokens> + (expandable)}} +\bookmark{\expanded} +================= ERROR +Expands <tokens> in exactly the same way as \type{\message}. +In contrast to \type{\edef}, macro parameter characters do not need to +be doubled. \type{\protected} macros are not expanded. +\introduced{1.40.20} +================= ERROR +================= ERROR +\pdftexprimitive{\Syntax{\ifincsname (expandable)}} +\bookmark{\ifincsname} +================= ERROR +This conditional is true if evaluated inside \type{\csname ... \endcsname}, +and false otherwise. +================= ERROR +================= ERROR +\pdftexprimitive{\Syntax{\ifpdfprimitive <control sequence> + (expandable)}} +\bookmark{\ifpdfprimitive} +================= ERROR +This condition checks if the following control sequence has its +primitive meaning. If it has, \type{\ifpdfprimitive} returns true. In +any other case (redefined, made \type{\undefined}, has never been +primitive) false is returned. \introduced{1.40.0} +================= ERROR +================= ERROR +flapping\pdftexprimitive{\Syntax{\partokencontext <number>}} +\bookmark{\partokencontext} +================= ERROR +The {\em par-token} (i.e., the token with the name given by +\type{\partokenname}, or \type{\par} by default; see +\type{\partokenname}, next) is inserted into the input stream in +different places, according to the \type{\partokencontext} value. This +value can be: +================= ERROR +0: {\em par-token} is inserted at empty lines (more exactly, when a + token category~5 is seen in state~$N$, reading a line); before + \type{\end}, \type{\vskip}, \type{\hrule}, \type{\unvbox}, and + \type{\halign}, if \TeX{} is in horizontal mode when those commands + are seen; and in various error recovery situations. These are the + standard cases, and this is the default value. +================= ERROR +1: {\em par-token} is inserted as above, and also at the end of + \type{\vbox}, \type{\vtop}, and \type{\vcenter}, if \TeX{} is in + horizontal mode at the time. +================= ERROR +2: {\em par-token} is inserted as above, and also at the end of + \type{\insert}, \type{\vadjust}, \type{\output}, \type{\noalign}, and + items of \type{\valign}, again if \TeX{} is in horizontal mode at the + time. +================= ERROR +With the default \type{\partokencontext=0}, \TEX\ behaves in its normal +way: the situations in cases 1 and 2 are processed by a direct call of +{\em end-paragraph} routine, with no emitted {\em par-token}. +================= ERROR +If \type{\partokencontext=1} then \TeX\ inserts the {\em par-token} in +additional cases: when vertical boxes are completed but horizontal mode +is not finished. Since vboxes are not uncommonly inserted directly by +users, with horizontal mode material, this allows macro programmers to +control all such boxes being finished by a {\em par-token}. An example: +================= ERROR +\starttyping +\partokenname\_mypar +\partokencontext=1 +\def\_mypar{Hi there!\endgraf} +\vbox{Vbox text.} +\stoptyping +================= ERROR +This will output ``\type{Hi there!''}\ after ``\type{Vbox text.}''. +================= ERROR +Finally, with \type{\partokencontext=2}, all cases where classical \TeX\ +uses the direct {\em end-paragraph} routine are changed to emit the {\em +par-token} instead. In contrast to case~1, these commands are rarely +invoked directly by users with horizontal mode material. +================= ERROR +The setting of the register \type{\partokencontext} is local. +\introduced{1.40.24} +================= ERROR +\pdftexprimitive{\Syntax{\partokenname <control sequence>}} +\bookmark{\partokenname} +================= ERROR +\TeX{} internally inserts a control sequence, named \type{\par} by +default, into the input stream at empty lines, the end of vboxes, and +various other places (see \type{\partokencontext}, above). Let's call this +control sequence the {\em par-token}. +================= ERROR +Executing \type{\partokenname}<control-sequence> changes the +name of the {\em par-token} from \type{\par} to the given +<control-sequence>. The setting performed by +\type{\partokenname} is global. +================= ERROR +This makes it possible to release the name \type{\par} to the ``user's +name space'', i.e., after \type{\partokenname}, users can define and use +\type{\par} as they wish without changing the behavior of anything +internal to \TeX{}. For example: +================= ERROR +\starttyping +\catcode`\_=11 +\partokenname\_mypar % use \_mypar at user level +\let\_mypar=\par % make \_mypar equivalent to built-in \par +\def\par{some random text} % redefine \par +Hello world. +================= ERROR +Goodbye. +\end +\stoptyping +================= ERROR +This will not output ``\type{some random text}'' (the definition of +\type{\par}), due to the \type{\partokenname} setting. +================= ERROR +By default, the meaning of the {\em par-token} is to end a paragraph +(also named as \type{\endgraf} in the plain \TEX\ format). It can be +changed as usual with, for example, \type{\def}. Naturally, it is the +control sequence name given to \type{\partokenname} that must be +redefined. Continuing the previous example (prior to the \type{\end}): +================= ERROR +\starttyping +\def\_mypar{Hi there!\endgraf} +Paragraph one. +================= ERROR +Paragraph two.\let\_mypar=\endgraf +\stoptyping +================= ERROR +This will output ``\type{Hi there!''}\ after ``\type{Paragraph one.}'', +before ending the paragraph. +================= ERROR +Another behavior of the {\em par-token} built into \TEX\ is that macros +not defined as \type{\long} cause the error ``runaway argument'' if the +{\em par-token} is scanned as a parameter. After +\type{\setpartokenname}, it will be the new control sequence name that +triggers this error, not \type{\par}. For example (still continuing the +same example): +================= ERROR +\starttyping +\def\amac#1{} +\amac{long test, no error: \par} +\amac{long test, gives error: \_mypar} +\stoptyping +================= ERROR +\introduced{1.40.24} +================= ERROR +\pdftexprimitive{\Syntax{\pdfprimitive <control sequence>}} +\bookmark{\pdfprimitive} +================= ERROR +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} +================= ERROR +%*********************************************************************** +================= ERROR +\subsection{Typesetting} +================= ERROR +\pdftexprimitive{\Syntax{\pdfinsertht <integer> + (expandable)}} +\bookmark{\pdfinsertht} +================= ERROR +If <integer> is the number of an insertion class, this command +returns the height of the corresponding box at the current time. +For instance, the following returns \type{12pt} in plain \TEX: +================= ERROR +\starttyping +Abc\footnote*{Whatever.}\par +\pdfinsertht\footins +\stoptyping +================= ERROR +================= ERROR +\pdftexprimitive{\Syntax{\pdflastxpos (read-only integer)}} +\bookmark{\pdflastxpos} +================= ERROR +This primitive returns an integer number representing the absolute $x$ +coordinate of the last point marked by \type{\pdfsavepos}. The unit is +`scaled points' (sp). +================= ERROR +================= ERROR +\pdftexprimitive{\Syntax{\pdflastypos (read-only integer)}} +\bookmark{\pdflastypos} +================= ERROR +Completely analogous to \type{\pdflastxpos}, returning the $y$ coordinate. +================= ERROR +================= ERROR +\pdftexprimitive{\Syntax{\pdfsavepos (h, v, m)}} +\bookmark{\pdfsavepos} +================= ERROR +This primitive marks the current absolute ($x,y$) position on the +media, with the reference point in the lower left corner. It is active +only during page shipout, when the page is finally assembled. The +position coordinates can then be retrieved by the \type{\pdflastxpos} +and \type{\pdflastypos} primitives, and \eg\ written out to some +auxiliary file. The coordinates can be used only after the current +\type{\shipout} has been finalized, therefore normally two \PDFTEX\ +runs are required to utilize these primitives. Starting with +\PDFTEX\ 1.40.0, this mechanism can be used also while running +in \DVI\ mode. +================= ERROR +================= ERROR +\pdftexprimitive{\Syntax{\quitvmode}} +\bookmark{\quitvmode} +================= ERROR +The primitive instructs \PDFTEX\ to quit vertical mode and start +typesetting a paragraph. Thus, \type{\quitvmode} has the same basic +effect as the \type{\leavevmode} macro from \type{plain.tex}. However, +\type{\leavevmode} expands the \type{\everypar} tokens list, which may +or may not be desired. \type{\quitvmode} does not expand +\type{\everypar}. \introduced{1.21a} +================= ERROR +================= ERROR +\pdftexprimitive{\Syntax{\vadjust + [<pre spec>] + <filler> + { <vertical mode material> } + (h, m) diff --git a/systems/doc/pdftex/manual/pdftex-t.tex b/systems/doc/pdftex/manual/pdftex-t.tex index 02af91417f..3df8c28ed7 100644 --- a/systems/doc/pdftex/manual/pdftex-t.tex +++ b/systems/doc/pdftex/manual/pdftex-t.tex @@ -1,7 +1,7 @@ % interface=english modes=letter,screen output=pdftex % vim: tw=79 -% $Id: pdftex-t.tex 875 2022-03-01 02:08:10Z karl $ +% $Id: pdftex-t.tex 904 2023-02-26 18:01:11Z karl $ % The number of lines on the title page depends on exactly % what \PDF\ code is generated. @@ -38,9 +38,10 @@ August\or September\or October\or November\or December\else ERROR\fi} } -\svnscan $Id: pdftex-t.tex 875 2022-03-01 02:08:10Z karl $ +\svnscan $Id: pdftex-t.tex 904 2023-02-26 18:01:11Z karl $ -\def\currentpdftex{1.40.22} +\def\versplit#1#2#3{#1.#2#3}% 140 -> 1.40 +\def\currentpdftex{\expandafter\versplit\the\pdftexversion.\pdftexrevision} %*********************************************************************** @@ -181,6 +182,7 @@ % introduced \def\introduced#1{The primitive was introduced in \PDFTEX\ #1.} +\def\introducedplural#1{The primitives were introduced in \PDFTEX\ #1.} % to get bookmarks for primitives like \ifpdfprimitive \appendtoks\def\tex#1{\string\\#1}\to\simplifiedcommands @@ -729,9 +731,9 @@ unused). The actual starting point of the file's object structure is defined after the \type{trailer}: the \type{/Root} entry points to the \type{/Catalog} object (no.~9). In this object the viewer can find the pointer \type{/Pages} to the page list object (no.~5). In our example we -have only one page. The trailer also holds an \type{/Info} entry, which -points to an object (no.~10) with a bit more about the document. Just -follow the thread: +have only one page. The trailer also usually holds an \type{/Info} +entry, which points to an object (no.~10) with a bit more about the +document. We can follow the thread: \startnarrower \type{/Root} $\longrightarrow$ object~9 $\longrightarrow$ @@ -771,18 +773,19 @@ example only a \type{/Font} object (no.~4) is referenced, which in turn tells that the text is typeset in \type{/Font} \type{/Times-Roman}. The \type{/Font} object points also to a \type{/Widths} array (object no.~7) that tells for each character by how much the viewer must move forward -horizontally after typesetting a glyph. More details about the font -can be found in the \type{/FontDescriptor} object (no.~8); if a font -file is embedded, this object points to the font program stream. But as -the Times-Roman font used for our example is one of the 14 so||called -standard fonts that should always be present in any \PDF\ viewer and -therefore need not be embedded in the \PDF\ file, it is left out here -for brevity. However, when we use for instance a Computer Modern Roman -font, we have to make sure that this font is later available to the \PDF\ -viewer, and the best way to do this is to embed the font. -It's highly recommended nowadays to embed even the standard fonts; -you can't know how it looks exactly at the viewer side unless you embed -every font. +horizontally after typesetting a glyph. + +More details about the font can be found in the \type{/FontDescriptor} +object (no.~8); if a font file is embedded, this object points to the +font program stream. But as the Times-Roman font used for our example is +one of the 14 so||called standard fonts that should always be present in +any \PDF\ viewer and therefore need not be embedded in the \PDF\ file, +it is left out here for brevity. However, when we use for instance a +Computer Modern Roman font, we have to make sure that this font is later +available to the \PDF\ viewer, and the best way to do this is to embed +the font. It's highly recommended nowadays to embed even the standard +fonts; you can't know how it looks exactly at the viewer side unless you +embed every font. In this simple file we don't specify in what way the file should be opened, for instance full screen or clipped. A closer look at the page object no.~2 @@ -955,7 +958,7 @@ Some nice samples of \PDFTEX\ output can be found at \PDFTEX\ can work with Type~1 and TrueType fonts (and to some extent also with OpenType fonts). Font files should be available and embedded -for all fonts used in the generated PDF. It is possible to use +for all fonts used in the generated \PDF. It is possible to use \METAFONT||generated fonts in \PDFTEX\ --- but it is strongly recommended not to use these fonts if an equivalent is available in Type~1 or TrueType format, if only because bitmap Type~3 fonts render @@ -1574,11 +1577,6 @@ new Didot (1\,nd~=~0.375\,mm) and the new Cicero (1\,nc~=~12\,nd) } \Syntax{ -\Something{pdfliteral spec} \Means % - \Literal{direct} \Or \Literal{page} -} - -\Syntax{ \Something{pdfspecial spec} \Means % \Lbrace \Optional{\Something{pdfspecial id} % \Optional{\Something{pdfspecial modifier}}} % @@ -1782,7 +1780,7 @@ precision. This parameter is read when \PDFTEX\ writes a real number to the \PDF\ output. When including huge \METAPOST\ images using \filename {supp-pdf.tex}, one can -limit the accuracy to two digits by typing: \type{\twodigitMPoutput}. +limit the accuracy to two digits with: \type{\twodigitMPoutput}. \pdftexprimitive{\Syntax{\Tex{\pdfhorigin} \Whatever{dimen}}} \bookmark{\tex{pdfhorigin}} @@ -1838,6 +1836,12 @@ the wished true page height. \subsection[sec.docinfocatalog]{Document info and catalog} +\pdftexprimitive{\Syntax{\Tex{\pdfinfoomitdict} \Whatever{integer}}} +\bookmark{\tex{pdfinfoomitdict}} + +If nonzero, omit the \type{/Info} dictionary completely, as required by +the \PDF\ A-4 standard. \introduced{1.40.25} + \pdftexprimitive{\Syntax{\Tex{\pdfinfo} \Something{general text}}} \bookmark{\tex{pdfinfo}} @@ -2631,23 +2635,78 @@ Minimal example: \bookmark{\tex{pdfinterwordspaceon}} \pdftexprimitive{\Syntax{\Tex{\pdfinterwordspaceoff}}} \bookmark{\tex{pdfinterwordspaceoff}} +\pdftexprimitive{\Syntax{\Tex{\pdfspacefont} \Something{general text}}} +\bookmark{\tex{pdfspacefont}} + +The first two commands insert corresponding whatsit nodes which turn +on/off generation of faked interword spaces in the \PDF\ output (they +cause errors in \DVI\ 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 of the typeset output. + +This works roughly as follows: with \type{\pdfinterwordspaceon}, +\PDFTEX\ will guess when an interword space should be inserted, based on +movement within some limits in horizontal direction. When found, +\PDFTEX\ inserts a true space character into the \PDF\ page description +for the viewers, and adjusts the next movement so that the next +character will be in the expected position, according to normal \TEX\ +behavior. + +Where does that \quotation{true space character} come from? +There are two possibilities. + +\startitemize +\item If the current font has a real space character, it is used. +\PDFTEX\ considers a font to have such a space character if 1)~the font +has an encoding vector (\type{.enc} file) specified in its map entry, +and 2)~the encoding has a glyph named \type{space} (that is, the +PostScript name \type{/space}) at slot 32. For example, the font +\type{texnansi-lmr10} uses the encoding file \type{lm-texnansi.enc}, +which has such an entry. + +\item +If the current font does not have such a space character (this is the +case for most traditional \TEX\ fonts, such as \type{cmr10} and +\type{ec-lmr10}), \PDFTEX\ will use the space character from a special +fallback font named (by default) \type{pdftexspace}[\type{.tfm}]. +\PDFTEX\ automatically defines a map entry for this font which looks as +follows: + +\starttyping +\pdfmapline{=pdftexspace PdfTeX-Space <pdftexspace.pfb} +\stoptyping -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. +The \type{pdftexspace.tfm} and \type{pdftexspace.pfb} files are expected +to be available to \PDFTEX\ just like any other font. (They are +distributed with \PDFTEX.) The \type{pdftexspace} font was constructed +by hand; it has a space character that is .333em (and no other +characters). + +It is possible to use a different fallback font for the space character +by specifying \type{\pdfspacefont}\Lbrace \Something{somefont}\Rbrace. +(This is most likely to be useful for testing or debugging.) In this +case, \PDFTEX\ assumes that the given font has a real space character at +slot 32, and that any necessary corresponding map entry exists. For +example: -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. +\starttyping +\pdfspacefont{texnansi-lmr10} % use space char from this font if + % current font has no space char +\stoptyping +\stopitemize + +History: Before \PDFTEX\ version 1.40.25, no check was made for a +\type{space} character in the current font, the fallback font was named +\type{dummy-space}, and its space character was tiny, 0.001em. It turned +out that \PDF\ viewers were unhappy with this tiny space, especially +with tagged \PDF. Example of usage (see also the \type{fake-interword-space.tex} test file): \starttyping Text with no interword spaces. -\pdfmapline{+dummy-space <dummy-space.pfb} \pdfglyphtounicode{space}{0020} \pdfinterwordspaceon @@ -2657,7 +2716,7 @@ Switch to text with faked interword spaces. Back to text with no interword spaces. \stoptyping -\introduced{1.40.15} +\introducedplural{1.40.15, 1.40.25} \pdftexprimitive{\Syntax{\Tex{\pdffakespace}}} \bookmark{\tex{pdffakespace}} @@ -2888,7 +2947,7 @@ page\_height}\type{]}). (This behavior was introduced in version \bookmark{\tex{pdfpageresources}} These tokens are added to the resource dictionary for all pages, before -the font, XOBject, and other resources. +the font, XOBject, and ProcSet resources. \starttyping \pdfpageresources{/MyPageResourceAttribute /MyValue} @@ -2907,6 +2966,20 @@ will expand to that object number. \Eg, if the dictionary for page~5 of the \TEX\ document is contained in \PDF\ object no.~18, \tex{pdfpageref5} expands to the number 18. +\pdftexprimitive{\Syntax{\Tex{\pdfomitprocset} \Whatever{integer}}} +\bookmark{\tex{pdfomitprocset}} + +If this primitive parameter is zero (the default), the \type{/ProcSet} +array is included if \type{\pdfmajorversion} is~1, and omitted if +\type{\pdfmajorversion}$\,\ge\,2$. If this parameter is $>0$, +\type{/ProcSet} is always omitted. And if it is $<0$, \type{/ProcSet} is +always included. For information about what \type{/ProcSet} is, see the +\PDFReference\ or other documentation. + +\type{\ProcSet} was considered obsolete as of \PDF~1.4, but conforming +writers should continue to output it. It was formally deprecated in +\PDF~2.0.\introduced{1.40.25} + %*********************************************************************** \subsection{Form XObjects} @@ -3424,7 +3497,7 @@ While all graphics and text in a \PDF\ document have relative positions, annotations have internally hard||coded absolute positions. Again this is for the sake of speed optimization. The main disadvantage is that these annotations do {\em not} obey transformations issued by \type -{\pdfliteral}'s. +{\pdfliteral}s. The \Something{action spec} specifies the action that should be performed when the hyperlink is activated, one of (see the syntax @@ -3627,33 +3700,39 @@ an article thread. \subsection{Literals and specials} \pdftexprimitive{\Syntax{\Tex{\pdfliteral} - \Optional{\Something{pdfliteral spec}} + \Optional{\Literal{shipout}} + \Optional{\Literal{direct} \Or \Literal{page}} \Something{general text} \Modelist{h, v, m} }} \bookmark{\tex{pdfliteral}} -Like \type{\special} in normal \TEX, this command inserts raw -\PDF\ code into the output. This allows support of color and text -transformation. This primitive is heavily used in the \METAPOST\ -inclusion macros. Normally \PDFTEX\ ends a text section in the \PDF\ -output and sets the transformation matrix to the current location on the -page before inserting \Something{general text}\unkern, however this can be -turned off by giving the optional keyword \Literal{direct}. This command -appends a whatsit node to the list being built. \Something{general text} -is expanded when the whatsit node is created and not when it is shipped -out, as with \type{\special}. - -Starting with version 1.30.0, \PDFTEX\ allows to use a new keyword -\type{page} instead of \type{direct}. Both modify the default behavior -of \type{\pdfliteral}, avoiding translation of the coordinates space -before inserting the literal code. The difference is that the \type{page} +Analogous to \type{\special} in the original \TEX, this command inserts +raw \PDF\ code into the output, appending a whatsit node to the list +being built. This allows support of color and text transformation, among +other things. + +By default, \Something{general text} is expanded immediately, when the +whatsit node is created, as with \type{\special}. Starting with version +1.40.25, the optional keyword \Literal{shipout} can be used to delay +expansion of \Something{general text} until the whatsit node is shipped +out, as with non-\type{\immediate} \type{\write}. + +Normally, \PDFTEX\ ends a text section in the \PDF\ output and sets the +transformation matrix to the current location on the page before +inserting \Something{general text}\unkern; this can be turned off by +giving the optional keyword \Literal{direct}. + +Starting with version 1.30.0, \PDFTEX\ supports the keyword \type{page} +in addition to \type{direct}. Both modify the default behavior of +\type{\pdfliteral}, avoiding translation of the coordinate space before +inserting the literal code. The difference is that the \type{page} keyword instructs \PDFTEX\ to close a \type{BT ET} text block before -inserting anything. It means that the literal code inserted refers to the -origin (lower||left corner of the page) and can be safely enclosed with -\type{q Q}. Note, that in most cases using \type{q Q} operators inside -\type{\pdfliteral} with \type{direct} keyword will produce corrupted -\PDF\ output, as the \PDF\ standard doesn't allow to do anything like +inserting anything. This means that the literal code inserted refers to +the \PDF\ origin (lower-left corner of the page) and can be safely +enclosed with \type{q Q}. In contrast, using \type{q Q} operators inside +\type{\pdfliteral} with the \type{direct} keyword will produce corrupted +\PDF\ output, as the \PDF\ standard doesn't allow doing anything like this within a \type{BT ET} block. % HE: \unkern is a kludge here; wanted to have tight "{pdf:" @@ -3678,6 +3757,20 @@ This is equivalent to \Syntax{\Tex{\pdfliteral} \Literal{direct} \Lbrace This is equivalent to \Syntax{\Tex{\pdfliteral} \Literal{page} \Lbrace \Something{text} \Rbrace}. +\pdftexprimitive{\Syntax{\Tex{\special} \Optional{\Literal{shipout}} + \Lbrace\unkern \Something{general text} \Rbrace}} +\bookmark{\tex{special\ shipout}} + +Starting with version 1.40.25, \PDFTEX\ extends the \type{\special} +primitive to support the optional keyword \Literal{shipout}. This delays +expansion of \Something{general text} until the page is shipped out, as +with non-\type{\immediate} \type{\write}. By default, \Something{general +text} is expanded immediately. + +\Syntax{\Tex{\special} \Literal{shipout} \Lbrace \unkern\Literal{pdf:} +\Something{text} \Rbrace} is equivalent to \Syntax{\Tex{\pdfliteral} +\Literal{shipout} \Lbrace \Something{text} \Rbrace}. + %*********************************************************************** \subsection{Strings} @@ -3907,8 +4000,8 @@ example, the first ten bytes of the source of this manual are {\tt As of \TEXLIVE\ 2020, the \type{\input} primitive in all \TEX\ engines, including \PDFTEX, now also accepts a group-delimited filename argument, -as a system-dependent extension, as in \type{\input\Lbrace -foo.tex\Rbrace}. The usage of \type{\input} with a standard +as a system-dependent extension, as in \type{\input} \Lbrace +\type{foo.tex} \Rbrace. The usage of \type{\input} with a standard space/token-delimited filename is completely unchanged. This group-delimited argument was previously implemented in Lua\TEX; now @@ -4315,11 +4408,10 @@ Now the \type{\b} expansion is not logged either, since the expansion depth is higher than the \type{\tracingstacklevels} value. The intended use of \type{\tracingstacklevels} is not so much to -truncate logging as to indicate the expansion levels for detailed -debugging. Thus normally it would be set to a large number -(\type{\maxdimen}, say), so that everything is fully logged, with the -addition of the expansion level indication with the number of dots in -the prefix. +truncate logging as to indicate expansion levels for detailed debugging. +Thus normally it would be set to a large number (\type{\maxdimen}, say), +so that everything is fully logged, with the addition of the expansion +level indication with the number of dots in the prefix. The behavior is the same in all \TeX\ engines except the original \TEX\ and \eTeX, where \type{\tracingstacklevels} remains undefined. @@ -4331,8 +4423,8 @@ and \eTeX, where \type{\tracingstacklevels} remains undefined. If this primitive parameter has a value corresponding to an open output stream (which has been opened with \type{\openout}), then any \type{\show}, \type{\showthe}, \type{\showbox} or \type{\showlists} -commands do not write output to the terminal, but instead write to only -the referenced output stream, as if they were written with +commands do not write output to the terminal, but instead write to the +referenced output stream only, as if they were written with \type{\immediate\write}. For example: @@ -4397,19 +4489,17 @@ Returns the \PDFTEX\ banner message, \eg\ for the version used here: \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}. +\currentpdftex\ (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}. +version \currentpdftex\ (used to produce this document), it returns {\tt +\number\pdftexversion}. %*********************************************************************** @@ -4494,19 +4584,16 @@ uses its own Type~1 fonts, and needs no special attention. macro packages) can be redefined to produce literal \PDF, using some macros written by Hans Hagen. -\description {\METAPOST} Although the output of \METAPOST\ is \POSTSCRIPT, -it is in a highly simplified form, and a \METAPOST\ to \PDF\ conversion -(\MPTOPDF, written by Hans Hagen and Tanmoy Bhattacharya) is implemented -as a set of macros which reads \METAPOST\ output and supports all of -its features. - -For new work, the \METAPOST\ route is highly recommended. For the future, -Adobe has announced that they will define a specification for \quote -{encapsulated \PDF}. +\description {\METAPOST} Although the output of \METAPOST\ is +\POSTSCRIPT, it is in a highly simplified form, and a \METAPOST\ to +\PDF\ conversion (\MPTOPDF, available as \type{supp-pdf.tex} and +\type{supp-pdf.mkii}, written by Hans Hagen and Tanmoy Bhattacharya) is +implemented as a set of macros which reads \METAPOST\ output and +supports all of its features. The inclusion of raw \POSTSCRIPT\ commands |<|a technique utilized by for instance the \type{pstricks} package|>| cannot directly be -supported. Although \PDF\ is direct a descendant of \POSTSCRIPT, it +supported. Although \PDF\ is a direct descendant of \POSTSCRIPT, it lacks any programming language commands, and cannot deal with arbitrary \POSTSCRIPT. @@ -5155,7 +5242,7 @@ the source code by typing: texexec --result=pdftex-a.pdf pdftex-t \stoptyping -Or in letter size: +Or for letter size: \starttyping texexec --mode=letter --result=pdftex-l.pdf pdftex-t |