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

[commits+karl at tug.org]

Revision: 857
          http://tug.org/svn/pdftex?view=revision&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:
--------------
    branches/stable/doc/manual/ChangeLog
    branches/stable/doc/manual/pdftex-t.tex
    branches/stable/doc/manual/pdftex-w.pdf

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}}}
+\bookmark{\tex{partokenname}}
+
+\TeX{} internally inserts a control sequence, named \type{\par} by
+default, into the input stream at empty lines, the end of vboxes, and
+various 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:
+
+\starttyping
+\catcode`\_=11
+\partokenname\_mypar % use \_mypar at user level
+\let\_mypar=\par     % make \_mypar equivalent to built-in \par
+%
+\def\par{some random text} % redefine \par
+%
+Hello world.
+
+Goodbye.
+\end
+\stoptyping
+
+This will not output ``\type{some random text}'' (the definition of
+\type{\par}), due to the \type{\partokenname} setting.
+
+By default, the meaning of the {\em par-token} is to end a paragraph
+(also named as \type{\endgraf} in the plain \TEX\ format). It can be
+changed as usual with, for example, \type{\def}. Naturally, it is the
+control sequence name given to \type{\partokenname} that must be
+redefined. Continuing the previous example (prior to the \type{\end}):
+
+\starttyping
+\def\_mypar{Hi there!\endgraf}
+Paragraph one.
+
+Paragraph two.\let\_mypar=\endgraf
+\stoptyping
+
+This will output ``\type{Hi there!''}\ after ``\type{Paragraph one.}'',
+before ending the paragraph.  
+
+Another behavior of the {\em par-token} built into \TEX\ is that macros
+not defined as \type{\long} cause the error ``runaway argument'' if the
+{\em par-token} is scanned as a parameter. After
+\type{\setpartokenname}, it will be the new control sequence name that
+triggers this error, not \type{\par}. For example (still continuing the
+same example):
+
+\starttyping
+\def\amac#1{}
+\amac{long test, no error: \par}
+\amac{long test, gives error: \_mypar}
+\stoptyping
+
+\introduced{1.40.24}
+
+\pdftexprimitive{\Syntax{\tex{partokencontext} \Something{number}}}
+\bookmark{\tex{partokencontext}}
+
+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:
+
+\starttyping
+\partokenname\_mypar
+\partokencontext=1
+\def\_mypar{Hi there!\endgraf}
+\vbox{Vbox text.}
+\stoptyping
+
+This will output ``\type{Hi there!''}\ after ``\type{Vbox text.}''.
+
+Finally, with \type{\partokencontext=2}, all cases where classical \TeX\
+uses the direct {\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.
+\introduced{1.40.24}
+
 \pdftexprimitive{\Syntax{\tex {pdfprimitive} \Something{control sequence}}}
 \bookmark{\tex{pdfprimitive}}
 

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