[latex3-commits] [git/LaTeX3-latex3-latex2e] copyedits-chris: ltpara Temporary local 20/09 (a712a3d4)
Chris Rowley
car222222 at github.github.io
Mon Sep 20 07:31:57 CEST 2021
Repository : https://github.com/latex3/latex2e
On branch : copyedits-chris
Link : https://github.com/latex3/latex2e/commit/a712a3d4b84311ef5cb3dea2cd92b1b5858c1735
>---------------------------------------------------------------
commit a712a3d4b84311ef5cb3dea2cd92b1b5858c1735
Author: Chris Rowley <car222222 at users.noreply.github.com>
Date: Mon Sep 20 12:31:57 2021 +0700
ltpara Temporary local 20/09
Need to integrate with DC changes
>---------------------------------------------------------------
a712a3d4b84311ef5cb3dea2cd92b1b5858c1735
base/ltpara.dtx | 150 ++++++++++++++++++++++++++++----------------------------
1 file changed, 76 insertions(+), 74 deletions(-)
diff --git a/base/ltpara.dtx b/base/ltpara.dtx
index 22edac2f..c07e74da 100644
--- a/base/ltpara.dtx
+++ b/base/ltpara.dtx
@@ -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,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}
@@ -538,7 +539,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 +630,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 +645,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 +829,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 +928,7 @@
% \end{itemize}
%
% Unfortunately, \TeX{} has some (these days) unnecessary
-% optimization: if a \cs{vbox} ends and \TeX{} is still in
+% optimisations: 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 +941,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.
@@ -968,7 +969,7 @@
% { ...
% \end{macrocode}
% 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 are aren't using 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 +982,18 @@
% \afterassignment\lst at 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 at 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 at skip}) and
% the \cs{lst at vskip} will get inserted into the middle of the
% conditional. The \cs{lst at 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 at vskip} that is causing it. That happened
+% changed modes even if you don't have any hook code(!): it is
+% the inserted \cs{lst at 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 +1003,17 @@
\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.
%
% 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,24 +1022,24 @@
% \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 at after@para at 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
+% \cs{tex_par:D} is called) is to add a kern item XXXX DC 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.
+% removing two glue items instead of just the last one, which would be wrong.
+% We use a kern as that is minimally faster. XXX DC
%
% There is however one other \TeX{} optimization that hurts: in a
% sequence like this \verb=$$ ... $$ \par= \TeX{} will be in
@@ -1050,11 +1052,11 @@
% simply goes silently to vmode. Now if we would had 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 \cs{parfillskip}. XXX not needed!!
%
-% We therefore check if the current hlist is empty
+% We therefore check if the current hlist is empty XXX DC but add nonempty
% (\cs{tex_lastnodetype:D} has the value \texttt{-1} and
-% only if not we add our kern.
+% only if not we add our kern. XXX See DC but use “if so add extra zero skip”
% \begin{macrocode}
\if_int_compare:w 0 < \tex_lastnodetype:D
\tex_kern:D \c_zero_dim
@@ -1070,8 +1072,8 @@
\@kernel at after@para at 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 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}
@@ -1080,7 +1082,7 @@
}
}
% \end{macrocode}
-%
+% And then we can use the primitive to truly end the paragraph.
% \begin{macrocode}
\tex_par:D
}
@@ -1157,9 +1159,9 @@
% \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:
More information about the latex3-commits
mailing list.