diff options
Diffstat (limited to 'macros/latex/base/ltpara.dtx')
-rw-r--r-- | macros/latex/base/ltpara.dtx | 253 |
1 files changed, 157 insertions, 96 deletions
diff --git a/macros/latex/base/ltpara.dtx b/macros/latex/base/ltpara.dtx index 5ab52a5e9b..a2da67198a 100644 --- a/macros/latex/base/ltpara.dtx +++ b/macros/latex/base/ltpara.dtx @@ -14,8 +14,8 @@ %%% From File: ltpara.dtx % % \begin{macrocode} -\def\ltparaversion{v1.0g} -\def\ltparadate{2021/05/27} +\def\ltparaversion{v1.0k} +\def\ltparadate{2021/11/11} % \end{macrocode} %<*driver> \documentclass{l3doc} @@ -23,6 +23,7 @@ %\usepackage{ltpara} % Fixing footnotes in functions and variables: this should be in l3doc! + \newcommand\fixfootnote[2]{\footnotemark \AddToHookNext{env/#1/after}{\footnotetext{#2}}} \AddToHook{env/function/begin}{\def\footnote{\fixfootnote{function}}} @@ -122,8 +123,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 +134,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 +153,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 +184,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 +216,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 +250,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 +328,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 +417,20 @@ % \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). +% (along with \cs{par} remaining subject to its current meaning). % -% The \pkg{expl3} name for the functionality is \cs{para_end:}. +% The \pkg{expl3} name for this functionality is \cs{para_end:}. % \end{function} % % \begin{quote} @@ -468,7 +470,7 @@ % % The commands \cs{RawIndent} and \cs{RawNoindent} are not meant % for normal paragraph building (where the result is a textual -% paragraph in the the traditional meaning of the word), but for +% paragraph in the traditional meaning of the word), but for % special cases where \TeX{}'s low-level algorithm is used to % achieve special effects, but where the result is not a % \enquote{paragraph}. @@ -538,7 +540,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} @@ -602,8 +604,8 @@ % % \subsubsection{Mark the first paragraph of each \env{itemize}} % -% The code for this is rather simple. We apply hook code that is -% executed only once inside a hook that is executed at the begin of +% The code for this is rather simple. We supply some code that is +% executed only once inside a hook at the start of % each \env{itemize}. We explicitly change the color back and % forth so that we don't introduce grouping around the paragraph. %\begin{verbatim} @@ -629,7 +631,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 +646,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 +830,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 +929,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 +942,11 @@ % \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. % % -% 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,110 +955,158 @@ % 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} % +% CCC Maybe needs more explanation. +% 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. +% +% If \cs{para_end:} is executed while \TeX{} is currently doing a +% low-level assignment the test for horizontal mode may get +% executed as part of the assignment. That is normally not an issue +% but we just found one case where it is: +%\begin{verbatim} +% \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 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(!): 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 that any scanning is first stopped, thus: +% \begin{macrocode} + \scan_stop: +% \end{macrocode} +% % \begin{macrocode} \mode_if_horizontal:TF { \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. +% +% As in other simular cases, it maybe best to add here +% a \cs{nobreak} in case the hook itself adds glue and thus +% creates a non-explicit and unwanted potential breakpoont. +% On the other hand (as has been argued) the code in the hook +% should perhaps have the responsibility for adding such a +% guard penalty in this casse. +% This needs further analysis and decisions (as in emails). +% +% In either case, good documentation of these hooks is essential, +% covering what the hook may or should provide and all +% such related considerations convernimg the content. % % 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 -% remove one using \cs{tex_unskip:D}, if there wasn't one this will +% remove one using \cs{tex_unskip:D}: if there wasn't one this will % do nothing. % \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 kern 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 a kern as that is minimally faster. +% \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 +% sequence like this \verb=$$ ... $$ \par= (with \cs{par} being the primitive) +% \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 had added something (to +% simply goes silently to vmode. +% +% 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 is empty -% (\cs{tex_lastnodetype:D} has the value \texttt{-1} and -% only if not we add our kern. +% We therefore check if the current hlist does end in glue +% (\cs{tex_lastnodetype:D} has the value \texttt{11}) and +% if so we add a zero-length guard skip which will be removed by the +% following \cs{tex_par:D}. +% \changes{v1.0i}{2021/09/18}{Use skip rather than kern as guard.} % \begin{macrocode} - \if_int_compare:w 0 < \tex_lastnodetype:D - \tex_kern:D \c_zero_dim + \if_int_compare:w 11 = \tex_lastnodetype:D + \tex_hskip:D \c_zero_dim \fi: % \end{macrocode} % 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} % Finally close out the nested conditionals. % \begin{macrocode} } - } + } % \end{macrocode} -% +% And then we can use the primitive to truly end the paragraph. % \begin{macrocode} \tex_par:D } @@ -1090,7 +1140,7 @@ \@@_handle_indent: \the\everypar } } - { \msg_error:nn { kernel }{ raw-para } } + { \msg_error:nn { latex2e }{ raw-para } } \tex_indent:D } % \end{macrocode} @@ -1103,7 +1153,7 @@ \tex_everypar:D { \g_@@_standard_everypar_tl } \the\everypar } } - { \msg_error:nn { kernel }{ raw-para } } + { \msg_error:nn { latex2e }{ raw-para } } \tex_noindent:D } % \end{macrocode} @@ -1133,10 +1183,11 @@ % \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}. +% % \begin{macrocode} \cs_set_eq:NN \par \para_end: \cs_set_eq:NN \@@par \para_end: @@ -1161,7 +1212,7 @@ % The first argument is the hook name second the mode % it should have stayed in but didn't. % -% \begin{macrocode} +% \begin{macrocode} \msg_new:nnnn { hooks } { para-mode } { Illegal~mode~ change~ in~ hook~ 'para/#1'.\\ @@ -1175,10 +1226,11 @@ } % \end{macrocode} % +% \changes{v1.0i}{2021/08/27}{Internal message name changes} % And here is one used in the \enquote{raw} commands when they are -% used outside of vertical mode. +% used outside of vertical mode. % \begin{macrocode} -\msg_new:nnnn { kernel } { raw-para } +\msg_new:nnnn { latex2e } { raw-para } { Not~ in~ vertical~ mode. } @@ -1206,7 +1258,17 @@ %<latexrelease>\cs_set_eq:NN \par \tex_par:D %<latexrelease>\cs_set_eq:NN \@@par \tex_par:D %<latexrelease>\cs_set_eq:NN \endgraf \tex_par:D -%<latexrelease> +%<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> @@ -1220,4 +1282,3 @@ \endinput %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % - |