[latex3-commits] [git/LaTeX3-latex3-latex2e] copyedits-chris: ltpara: further documentation ideas (f5e7acc0)

[Chris Rowley]

Repository : https://github.com/latex3/latex2e
On branch  : copyedits-chris
Link       : https://github.com/latex3/latex2e/commit/f5e7acc04c6166b2bd68583f2d6478f5498e5891

>---------------------------------------------------------------

commit f5e7acc04c6166b2bd68583f2d6478f5498e5891
Author: Chris Rowley <car222222 at users.noreply.github.com>
Date:   Mon Sep 20 17:59:02 2021 +0700

    ltpara: further documentation ideas
    
    local only for now


>---------------------------------------------------------------

f5e7acc04c6166b2bd68583f2d6478f5498e5891
 base/ltpara.dtx | 16 ++++++++++------
 1 file changed, 10 insertions(+), 6 deletions(-)

diff --git a/base/ltpara.dtx b/base/ltpara.dtx
index 7eb0891f..831a98f2 100644
--- a/base/ltpara.dtx
+++ b/base/ltpara.dtx
@@ -954,7 +954,7 @@
 %    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}
@@ -1013,7 +1013,7 @@
 %    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 this removal.
+%    to arrange for this removal.  XXX and penalty, just in case!
 %
 %    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
@@ -1035,11 +1035,11 @@
 %    \end{macrocode}
 %    The final action (before getting to the point where
 %    \cs{tex_par:D} is called) is to add an extra glue item so that the
-%    primitive is prevented from removing intended glue 
+%    primitive is prevented from removing intended glue XXX ??  
 %    (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.  XXX DC needs more rewriting
-%    We use glue (rather than a kern) so that  is minimally faster.  XXX DC
+%    We use glue (rather than a kern) so that  is minimally faster.  XXX DC Remove! 
 %
 %    There is however one other \TeX{} optimization that hurts: in a
 %    sequence like this \verb=$$ ... $$ \par=  \TeX{} will be in
@@ -1054,6 +1054,9 @@
 %    after the display and so we would end up with an empty paragraph
 %    just containing \cs{parfillskip}.   XXX not needed!! Bad text also.
 %
+%    More generally, it is always best not to add anything 
+%    non-essential (such as  guard items) to an empty list.  XXX ADDED
+%
 %    We therefore check whether the current hlist ends with a glue item  XXX DC add ie is nonempty?? 
 %    (\cs{tex_lastnodetype:D} has the value \texttt{11}) and
 %    if it does then we add an extra zero-length glue item as a guard, 
@@ -1067,14 +1070,15 @@
 %    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 at after@para at after
          }
 %    \end{macrocode}
-%    If we were not horizontal mode then the earlier hook
+%    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} }