summaryrefslogtreecommitdiff
path: root/macros/latex-dev/base/ltpara.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex-dev/base/ltpara.dtx')
-rw-r--r--macros/latex-dev/base/ltpara.dtx214
1 files changed, 129 insertions, 85 deletions
diff --git a/macros/latex-dev/base/ltpara.dtx b/macros/latex-dev/base/ltpara.dtx
index bc51e4688f..9802bfd63a 100644
--- a/macros/latex-dev/base/ltpara.dtx
+++ b/macros/latex-dev/base/ltpara.dtx
@@ -14,8 +14,8 @@
%%% From File: ltpara.dtx
%
% \begin{macrocode}
-\def\ltparaversion{v1.0j}
-\def\ltparadate{2021/09/18}
+\def\ltparaversion{v1.0k}
+\def\ltparadate{2021/10/19}
% \end{macrocode}
%<*driver>
\documentclass{l3doc}
@@ -122,8 +122,8 @@
% \verb=\hbox{a\par b}= is ignored, but \verb=$a\par b$= would complain.
%
% If this primitive ends the paragraph it does some special
-% \enquote{end of horizontal list} processing, then calls \TeX{} paragraph
-% builder that breaks the horizontal list into lines then these
+% \enquote{end of horizontal list} processing, then calls \TeX{}’s paragraph
+% builder; this breaks the horizontal list into lines and then these
% lines are added as boxes to the enclosing vertical list and
% \TeX{} returns to vertical mode.
%
@@ -133,13 +133,14 @@
% automatically changed to a \cs{par} command which is then
% executed. The other possibility is that \TeX{} encounters a
% command which is incompatible with horizontal processing, e.g.,
-% \cs{vskip} (a request for adding vertical space). In such case it
+% \cs{vskip} (a request for adding vertical space). In such cases it
% silently backs up, and inserts a \cs{par} in the hope that this
-% gets it out of horizontal mode and makes the offending command
+% gets it out of horizontal mode and makes the vertical command
% acceptable.
% The important point to note here is that \TeX{} really inserts
-% the command \cs{par} which can be redefined. Thus, it may not have
+% the command with the name \cs{par}, which can be redefined.
+% Thus, it may not have
% its original \enquote{primitive} meaning and therefore may not end the
% horizontal list and call the paragraph builder. This approach
% offers some flexibility but also allows you to easily produce a
@@ -151,31 +152,30 @@
% then sees \cs{vskip} and inserts \cs{par} to end the
% paragraph. But this now only runs \cs{relax} so nothing changes
% and \cs{vskip} is read again, issues a \cs{par} which \ldots. In
-% short, it takes a plain \TeX{} document with five tokens to run
-% forever (as not even memory is consumed and therefore eventually
+% short, it only takes a plain \TeX{} document with five tokens to run
+% forever (since no memory is consumed and therefore eventually
% exhausted).
%
-% There are no other ways than changing \cs{par} to gain control at
+% There is no way other than changing \cs{par} to gain control at
% the end of a paragraph, i.e., there is no token list like
-% \cs{everypar} that is inserted, i.e., the only way to change the
-% default behavior is to modify the action that \cs{par} executes
+% \cs{everypar} that is inserted. Hence the only way to change the
+% default behavior is to modify the action that \cs{par} executes,
% with similar issues as outlined before: different processes need
% to ensure that they do not overwrite their modifications or
% worse, think that the \cs{par} in front of them is the engine
% primitive while in fact it has already been changed by other
% code.
%
-%
% To make matters slightly worse there are a few places where
% \TeX{} handles the situation differently (most likely for speed
% reasons back when computers were much slower). If \TeX{} finds
% itself in unrestricted horizontal mode at the end of building a
-% vertical box (or an \cs{insert}, \cs{vadjust} or at the end of
+% vertical box (for an \cs{insert}, \cs{vadjust} or
% executing the output routine code), it will finish the horizontal
% list not by issuing a \cs{par} command (which would be consistent
-% with all other places, but by simply executing the primitive version
-% of \cs{par} regardless of the definition that \cs{par} has at the
-% time.
+% with all other places) but by simply executing the primitive meaning
+% of \cs{par}, regardless of the actual definition that \cs{par}
+% has at the time.
%
% Thus, if you have carefully crafted a redefined \cs{par} to execute
% some special actions at the end of a paragraph and you write
@@ -183,27 +183,28 @@
%\begin{verbatim}
% \vbox{Some paragraph ... text.}
%\end{verbatim}
-% you will find that your code has never run for the last paragraph
+% you will find that your code does not get run for the last paragraph
% in that box. \LaTeX{} avoids this problem, by making sure that
-% all its boxes (such as \cs{parbox} or the \env{minipage}
+% its boxes (such as \cs{parbox} or the \env{minipage}
% environment, etc.) all internally add an explicit \cs{par} at the
% end so that such code is run and \TeX{} finds itself in vertical
% mode already without the need to start up the paragraph builder
% internally. But, of course, this only works for boxes under direct
-% control of the \LaTeX{} kernel, if some package uses low-level
+% control of the \LaTeX{} kernel; if some package uses low-level
% \cs{vbox}es without adding this precaution the \TeX{}
% optimization kicks in and no special \cs{par} code is executed.
%
% And there is another optimization that is painful: if a paragraph
% is interrupted by a mathematical display, e.g., \verb=\[...\]= in
% \LaTeX{} or \verb=$$...$$= in plain \TeX{}, then \TeX{} will
-% resume horizontal mode afterward, i.e., build a new horizontal
-% list (without inserting an indentation box or \cs{everypar} at
-% that point). However, if that list immediately ends with an
+% resume horizontal mode afterward, i.e., it will start to build
+% a new horizontal
+% list without inserting an indentation box or \cs{everypar} at
+% that point. However, if that list immediately ends with an
% explicit or implicit \cs{par} then \TeX{} will simply throw away
% this \enquote{null} paragraph and not do its usual \enquote{end
-% of horizontal list} processing, so this special case need to be
-% accounted for when introducing some extended processing.
+% of horizontal list} processing, so this special case also needs to be
+% accounted for when introducing any extended processing.
%
%
%
@@ -214,8 +215,8 @@
% the start and end of the paragraph processing. The public hooks
% can be used by packages (or by the user in the preamble or
% within the document) and using the hook mechanisms it is possible
-% to reorder or arrange code from different packages in a way that
-% it can safely coexist.
+% to reorder or arrange code from different packages in such a way that
+% these can safely coexist.
%
% To make that happen we have to make use of the basic
% functionality that is offered by \TeX{}, e.g., we install
@@ -248,7 +249,7 @@
% Fortunately, \LaTeX{} has already redefined \cs{par} for its own
% purposes. As a result there aren't many packages that attempt to
% change \cs{par}, because without a lot of extra care that would
-% fail miserably. But bottom line, if you load a package that
+% fail miserably. But the bottom line is that, if you load a package that
% alters \cs{par} then the end of paragraph hooks are most likely
% not executing while that redefinition is
% active.\footnote{Similarly to the \cs{everypar} situation, the
@@ -326,7 +327,7 @@
%
% This hook is executed at the end of a paragraph when \TeX{} is
% ready to return to vertical mode and after it has removed the
-% last horizontal glue (but not kern) placed on the horizontal
+% last horizontal glue (but not any kerns) placed on the horizontal
% list. The code is still executed in horizontal mode so it is
% possible to add further horizontal material at this point, but
% it should not alter the mode (even a temporary exit from
@@ -415,20 +416,30 @@
% \subsection{Altered and newly provided commands}
%
% \begin{function}{\par,\endgraf,\para_end:}
-% An explicit request for ending a paragraph is known in plain
-% \TeX{} under the name \cs{endgraf} where it simply calls the
-% paragraph primitive (regardless of what \cs{par} may have as its
-% current definition). In \LaTeX{} \cs{endgraf} with that behavior
-% was also made available.
+% An explicit request for ending a paragraph is provided in plain
+% \TeX{} under the name \cs{endgraf}, which simply uses the
+% primitive meaning (regardless of what \cs{par} may have as its
+% current definition). In \LaTeX{} \cs{endgraf} (with that behavior)
+% was originally also available.
%
% With the new paragraph handling in \LaTeX{}, ending a paragraph
% means a bit more than just calling the engine's paragraph
% builder: the process also has to add any hook code for the end of
% a paragraph. Thus
% \cs{endgraf} was changed to provide this additional functionality
-% (and so by extension \cs{par} subject to its current meaning).
-%
-% The \pkg{expl3} name for the functionality is \cs{para_end:}.
+% (along with \cs{par} remaining subject to its current meaning).
+%
+% TEMP NOTE: Maybe endgraf should not be changed by LaTeX as it is
+% essentially not at all a part of LaTeX.
+% If it is too dangerous to leave it as
+% a synonym for the primitive, then we could just disable it.
+% [FMi:]
+% not in my opinion. It is used in many places and the redefinition is safe and does the right thing.
+% disabling it just means it breaks a lot of stuff for no reason.
+% [FMi:]
+% Note that the 2e kernel has been completely purged of endgrafs.
+%
+% The \pkg{expl3} name for this functionality is \cs{para_end:}.
% \end{function}
%
% \begin{quote}
@@ -538,7 +549,7 @@
% sequence numbers. This is most easily done using \pkg{expl3}
% functions, so we switch over. This is not a very general
% implementation, just enough for what we need and a bit of
-% \LaTeXe{} thrown in as well. When popping the result gets stored
+% \LaTeXe{} thrown in as well. When popping, the result gets stored
% in \cs{paracntvalue} and the \cs{ERROR} should never happen
% because it means we have tried to pop from an empty stack.
%\begin{verbatim}
@@ -629,7 +640,7 @@
% \subsubsection{Glue items between paragraphs (found with \pkg{fancypar})}
%
% In the past \LaTeX{} placed two glue items between two
-% consecutive paragraph, e.g.,
+% consecutive paragraphs, e.g.,
%\begin{verbatim}
% text1 \par text2 \par
%\end{verbatim}
@@ -644,12 +655,12 @@
% \glue(\parskip) 0.0
% \glue(\baselineskip) 5.16669
%\end{verbatim}
-% The reason is that we generate a \enquote{fake}'' paragraph to
+% The reason is that we generate a \enquote{fake} paragraph to
% gain control and safely add the early hooks, but this generates
% an additional glue item. That item doesn't contribute anything
-% vertically but ifsomebody writes code the unravels a constructed
+% vertically but if somebody writes code that unravels a constructed
% list using \cs{lastbox}, \cs{unskip} and \cs{unpenalty} then the
-% code has to remove one additional glue item or else will fail.
+% code has to remove one additional glue item or else it will fail.
%
% ^^A \subsubsection{}
@@ -828,8 +839,8 @@
%
% But if we have already replaced it by a token register then all
% they do is to give that token register a new name. Thus our code
-% in \cs{tex_everypar:D} would call \cs{everypar} (which is their
-% now token register) and the code that they added ends up in our
+% in \cs{tex_everypar:D} would call \cs{everypar} (which is now their
+% token register) and the code that they added ends up in our
% token register which is then never used at all. A bit mind
% boggling I guess.
%
@@ -927,7 +938,7 @@
% \end{itemize}
%
% Unfortunately, \TeX{} has some (these days) unnecessary
-% optimization: if a \cs{vbox} ends and \TeX{} is still in
+% optimizations: if a \cs{vbox} ends and \TeX{} is still in
% horizontal mode it simply exercises the paragraph builder instead
% of issuing a \cs{par}. It is therefore necessary for \LaTeX{} to
% ensure that this case doesn't happen and all boxes internally
@@ -940,11 +951,12 @@
% \texttt{latex.ltx}. For this \LaTeXe{} code has the following
% conventions: \cs{@@@@par} and \cs{endgraf} both refer to the
% default meaning (in the past this was the initex primitive) while
-% \cs{par} is the current meaning which may does something else.
+% \cs{par} is the current meaning which maybe does something else.
%
+% TEMP NOTE: See earlier note re endgraf.
%
-% We are now going to change this default meaning to run
-% \cs{para_end:} instead, which ultimately executes the initex
+% We are now going to change this default meaning to instead run
+% \cs{para_end:}, which ultimately executes the initex
% primitive but additionally adds our hooks when appropriate.
% This way the change is again transparent to the legacy \LaTeXe{}
% code.
@@ -953,22 +965,24 @@
% primitive and we achieve this by simply expanding it to the
% primitive which is available to us as \cs{tex_par:D}. This way we
% don't have to care about whether \TeX{} just does nothing (e.g.,
-% if in vertical mode already) or generate an error, etc.
+% if in vertical mode already) or generates an error, etc.
% \begin{macrocode}
\cs_new_protected:Npn \para_end: {
% \end{macrocode}
%
+% TEMP NOTE: What should happen if in outer hmode with an empty hlist?
+%
% The only case we care about is when we are in horizontal mode
% (i.e., doing typesetting) and not also in inner mode (i.e.,
% making paragraphs and not building an \cs{hbox}.
-% \begin{macrocode}
+%\begin{verbatim}
% \bool_lazy_and:nnT
% { \mode_if_horizontal_p: }
% { \bool_not_p:n { \mode_if_inner_p: } }
% { ...
-% \end{macrocode}
+%\end{verbatim}
% Since this is executed for each and every paragraph in a document
-% we try to stay a fast as possible, So we are aren't using the
+% we try to stay as fast as possible, so we do not use the
% above construct but two conditionals instead. Using low-level
% \cs{if_mode...} conditions would be even faster but has the
% danger to conflict with conditionals in the user hooks.
@@ -981,17 +995,18 @@
% \afterassignment\lst@vskip\@tempskipa \z@ \par
%\end{verbatim}
% If \TeX{} is in hmode while that assignment happens then the
-% \cs{par} is seen in hmode (because in the above case the
-% assignment isn't finished (one should have used \cs{z@skip} and
+% \cs{par} is seen in hmode because in the above case the
+% assignment may not be finished (one should have used \cs{z@skip}) and
% the \cs{lst@vskip} will get inserted into the middle of the
% conditional. The \cs{lst@vskip} then changes to vmode and you get
% a surprising error about the \texttt{para/end} hook having
-% changed modes even if you don't have any hook code because it is
-% the instered \cs{lst@vskip} that is causing it. That happened
+% changed modes even if you don't have any hook code(!): it is
+% the inserted \cs{lst@vskip} that is actually causing the change of
+% mode.This is what happened
% when the output routines got started while a \texttt{lstlisting}
% environment (that redefines \cs{vskip} in this way) was
% active. This is really faulty coding, but we try to be proactive
-% and guard the conditional so thatany scanning is stopped before it:
+% and guard the conditional so that any scanning is first stopped, thus:
% \begin{macrocode}
\scan_stop:
% \end{macrocode}
@@ -1001,17 +1016,26 @@
\mode_if_inner:F {
% \end{macrocode}
% In that case the action of the primitive would be to remove the
-% last glue (not kern) from the horizontal list constructed to form
-% a paragraph then append the a penalty of 10000 and the
-% \cs{parfillskip} at the end and pass the whole list to the
-% paragraph builder which breaks it into lines and \TeX{} then
+% last glue (but no kerns) from the horizontal list (constructed to form
+% a paragraph) and then to append a penalty of 10000 and the
+% \cs{parfillskip}; it then passes the whole list to the
+% paragraph builder, which breaks it into lines and \TeX{} then
% returns to vertical mode.
%
-% What we want to do instead is to add our hook code at the end of
-% the horizontal list before that happens and the code is passed to
-% the paragraph builder. If there was a glue item at the end then
+% What we want to do is to add this hook code at the end of
+% the horizontal list before any of the above happens.
+% If there was a glue item at the end of the list then
% it should get removed before the hook code gets added so we have
-% to arrange for its removal ourselves.
+% to arrange for this removal.
+%
+% TEMP NOTE: maybe a ‘nobreak’ should also be added?
+%
+% [FMi:]
+% sounds wrong to me, why?
+% [CCC:] See email: because the hook may add some material,
+% such as glue that might produce an unintended linebreak.
+% [FMi:]
+%
%
% There is not much point in checking if there was really a glue
% item at the end of the horizontal list, instead we simply try to
@@ -1020,38 +1044,44 @@
% \begin{macrocode}
\tex_unskip:D
% \end{macrocode}
-% The we execute the public hook (which may add final typesetting
-% material) followed by the kernel hook we need for adding tagging
+% We then execute the public hook (which may add some final typeset
+% material) followed by the kernel hook that we need for adding tagging
% support. None of this is supposed to change the mode---at the
% moment we make only a very simple test for this, more devious
-% changes go unnoticed, but too bad, that will then probably
-% badly backfire.
+% changes go unnoticed, but too bad as they will then probably
+% backfire badly.
% \begin{macrocode}
\hook_use:n{para/end}
\@kernel@after@para@end
\mode_if_horizontal:TF {
% \end{macrocode}
% The final action (before getting to the point where
-% \cs{tex_par:D} is called) is to add a glue item so that the
-% primitive is prevented from removing glue (if there was some). If
-% we don't do this and the
-% horizontal list ended in several glue items we would end up with
-% removing two instead of just the last one, which would be wrong.
-% We use glue (rather than a kern) as that will be removed by the primitive
-% par.
+% \cs{tex_par:D} is called) is to add an extra glue item so that the
+% primitive is prevented from removing intended glue
+% (if there was some). If we don't do this and the
+% horizontal list ends in several glue items we would end up removing
+% two glue items instead of just the last one, which would be wrong.
+% We use glue (rather than a kern) as that will be removed by the
+% primitive.
%
% There is however one other \TeX{} optimization that hurts: in a
% sequence like this \verb=$$ ... $$ \par= \TeX{} will be in
% horizontal mode after the display, ready to receive further
% paragraph text, but since the \cs{par} follows immediately there
% is a ``null'' paragraph at the end and \TeX{} simply throws that
-% away. The space between \verb=$$= and \cs{par} got already
+% away.
+% The space between \verb=$$= and \cs{par} got already
% dropped during the display processing so the \cs{par} is not
% removing any space and appending \cs{parfillskip}, instead it
-% simply goes silently to vmode. Now if we would have added something (to
+% simply goes silently to vmode.
+%
+% TEMP NOTE: Is this actually how it works?
+% For any current definition of par?
+%
+% Now if we would have added something (to
% prevent glue removal) that would look to \TeX{} like material
% after the display and so we would end up with an empty paragraph
-% just containing \cs{parfillskip}.
+% just containing a penalty and \cs{parfillskip}.
%
% We therefore check if the current hlist does end in glue
% (\cs{tex_lastnodetype:D} has the value \texttt{11}) and
@@ -1066,15 +1096,16 @@
% To run the \hook{para/after} hook we first end the
% paragraph. This means that the \cs{tex_par:D} at the very end is
% unnecessary but executing it there unnecessarily is better than
-% having code that test for all the different mode possibilities.
+% having code that tests for all the different mode possibilities.
% \begin{macrocode}
\tex_par:D
\hook_use:n{para/after}
\@kernel@after@para@after
}
% \end{macrocode}
-% If we haven't been in horizontal mode then the earlier hook
-% \hook{para/end} is at fault and we report that.
+% If we were not horizontal mode (the F case from above)
+% then the earlier hook
+% \hook{para/end} must have been at fault, so we report that.
% \begin{macrocode}
{ \msg_error:nnnn { hooks }{ para-mode }{end}{horizontal} }
% \end{macrocode}
@@ -1083,7 +1114,7 @@
}
}
% \end{macrocode}
-%
+% And then we can use the primitive to truly end the paragraph.
% \begin{macrocode}
\tex_par:D
}
@@ -1160,10 +1191,13 @@
% \begin{macro}[int]{\@@par}
%
% Having the new default definition for \cs{par} we also have to
-% set it up so that it gets used. This is needed in three places
+% set it up so that it gets used. This involves three commands:
% \cs{par}, \cs{@@par} (to which \LaTeX{} resets \cs{par}
-% occasionally) and \cs{endgraf} which is another name for the
+% occasionally) and \cs{endgraf}, which is another name for the
% ``default'' action of \cs{par}.
+%
+% TEMP NOTE: re endgraf again.
+%
% \begin{macrocode}
\cs_set_eq:NN \par \para_end:
\cs_set_eq:NN \@@par \para_end:
@@ -1235,6 +1269,16 @@
%<latexrelease>\cs_set_eq:NN \@@par \tex_par:D
%<latexrelease>\cs_set_eq:NN \endgraf \tex_par:D
%<latexrelease>
+% \end{macrocode}
+% We also need to clean up the primitive ``everypar'' as that
+% should no longer execute any code by default. And, of course,
+% make \cs{everypar} become the primitive again.
+% \changes{v1.0k}{2021/10/19}{Remove content from \cs{tex_everypar:D}
+% on rollback}
+% \begin{macrocode}
+%<latexrelease>\tex_everypar:D {}
+%<latexrelease>\cs_set_eq:NN \everypar \tex_everypar:D
+%<latexrelease>
%<latexrelease>\EndModuleRelease
\ExplSyntaxOff
%</2ekernel|latexrelease>