pdftex[857] branches/stable/doc/manual: document new primitives

commits+karl at tug.org commits+karl at tug.org
Sun Jul 25 17:45:27 CEST 2021

Revision: 857
Author:   karl
Date:     2021-07-25 17:45:27 +0200 (Sun, 25 Jul 2021)
Log Message:
document new primitives \partokenname, \partokencontext

Modified Paths:

Modified: branches/stable/doc/manual/ChangeLog
--- branches/stable/doc/manual/ChangeLog	2021-07-24 17:26:37 UTC (rev 856)
+++ branches/stable/doc/manual/ChangeLog	2021-07-25 15:45:27 UTC (rev 857)
@@ -1,3 +1,8 @@
+2021-07-25  Karl Berry  <karl at freefriends.org>
+	* pdftex-t.tex (\partokenname, \partokencontext): document these
+	new primitives.
 2021-07-24  Karl Berry  <karl at freefriends.org>
 	* pdftex-t.tex (Installation): rename this section from "Getting

Modified: branches/stable/doc/manual/pdftex-t.tex
--- branches/stable/doc/manual/pdftex-t.tex	2021-07-24 17:26:37 UTC (rev 856)
+++ branches/stable/doc/manual/pdftex-t.tex	2021-07-25 15:45:27 UTC (rev 857)
@@ -3976,6 +3976,123 @@
 primitive) false is returned.  \introduced{1.40.0}
+\pdftexprimitive{\Syntax{\tex{partokenname} \Something{control sequence}}}
+\TeX{} internally inserts a control sequence, named \type{\par} by
+default, into the input stream at empty lines, the end of vboxes, and
+various places (see \type{\partokencontext}, next). Let's call this
+control sequence the {\em par-token}.
+Executing \type{\partokenname}\Something{control-sequence} changes the
+name of the {\em par-token} from \type{\par} to the given
+\Something{control-sequence}. The setting performed by
+\type{\partokenname} is global.
+This makes it possible to release the name \type{\par} to the ``user
+name space'', i.e., after \type{\partokenname}, users can define and use
+\type{\par} as they need without changing the behavior of anything
+internal to \TeX{}. For example:
+\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.
+This will not output ``\type{some random text}'' (the definition of
+\type{\par}), due to the \type{\partokenname} setting.
+By default, the meaning of the {\em par-token} is to end a paragraph
+(also named as \type{\endgraf} in the plain \TEX\ format). It can be
+changed as usual with, for example, \type{\def}. Naturally, it is the
+control sequence name given to \type{\partokenname} that must be
+redefined. Continuing the previous example (prior to the \type{\end}):
+\def\_mypar{Hi there!\endgraf}
+Paragraph one.
+Paragraph two.\let\_mypar=\endgraf
+This will output ``\type{Hi there!''}\ after ``\type{Paragraph one.}'',
+before ending the paragraph.  
+Another behavior of the {\em par-token} built into \TEX\ is that macros
+not defined as \type{\long} cause the error ``runaway argument'' if the
+{\em par-token} is scanned as a parameter. After
+\type{\setpartokenname}, it will be the new control sequence name that
+triggers this error, not \type{\par}. For example (still continuing the
+same example):
+\amac{long test, no error: \par}
+\amac{long test, gives error: \_mypar}
+\pdftexprimitive{\Syntax{\tex{partokencontext} \Something{number}}}
+The {\em par-token} (i.e., the token with the name given by
+\type{\partokenname}, or \type{\par} by default; see
+\type{\partokenname} above) is inserted into the input stream in
+different places, according to the \type{\partokencontext} value. This
+value can be:
+0: {\em par-token} is inserted at empty lines (more exactly, when a
+   token category~5 is seen in state~$N$, reading a line); before
+   \type{\end}, \type{\vskip}, \type{\hrule}, \type{\unvbox}, and
+   \type{\halign}, if \TeX{} is in horizontal mode when those commands
+   are seen; and in various error recovery situations. These are the
+   standard cases, and this is the default value.
+1: {\it 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.
+2: {\it par-token} is inserted as above, and also at the end of
+  \type{\insert}, \type{\vadjust}, \type{\output}, \type{\noalign}, and
+  items of \type{\valign}, again if \TeX{} is in horizontal mode at the
+  time.
+With the default \type{\partokencontext=0}, \TEX\ behaves in its normal
+way: the situations in cases 1 and 2 are processed by a direct call of
+{\it end-paragraph} routine, with no emitted {\em par-token}.
+If \type{\partokencontext=1} then \TeX\ inserts the {\em par-token} in
+additional cases: when vertical boxes are completed but horizontal mode
+is not finished. Since vboxes are not uncommonly inserted directly by
+users, with horizontal mode material, this allows macro programmers to
+control all such boxes being finished by a {\em par-token}. An example:
+\def\_mypar{Hi there!\endgraf}
+\vbox{Vbox text.}
+This will output ``\type{Hi there!''}\ after ``\type{Vbox text.}''.
+Finally, with \type{\partokencontext=2}, all cases where classical \TeX\
+uses the direct {\it end-paragraph} routine are changed to emit the {\it
+par-token} instead. In contrast to case~1, these commands are rarely
+invoked directly by users with horizontal mode material.
+The setting of the register \type{\partokencontext} is local.
 \pdftexprimitive{\Syntax{\tex {pdfprimitive} \Something{control sequence}}}

Modified: branches/stable/doc/manual/pdftex-w.pdf
(Binary files differ)

More information about the pdftex-commits mailing list.