diff options
Diffstat (limited to 'macros/latex-dev/base/ltpara.dtx')
-rw-r--r-- | macros/latex-dev/base/ltpara.dtx | 214 |
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> |