[latex3-commits] [latex3/latex2e] ltmarks-enhance: added change entries typos and corrections (b6728fea)
github at latex-project.org
github at latex-project.org
Tue Nov 14 15:13:52 CET 2023
Repository : https://github.com/latex3/latex2e
On branch : ltmarks-enhance
Link : https://github.com/latex3/latex2e/commit/b6728feaadf93dd8911e3d27068cfcfd8460ed77
>---------------------------------------------------------------
commit b6728feaadf93dd8911e3d27068cfcfd8460ed77
Author: Frank Mittelbach <frank.mittelbach at latex-project.org>
Date: Tue Nov 14 15:13:52 2023 +0100
added change entries
typos and corrections
>---------------------------------------------------------------
b6728feaadf93dd8911e3d27068cfcfd8460ed77
base/changes.txt | 14 ++++++
base/ltmarks.dtx | 140 +++++++++++++++++++++++++++++++------------------------
2 files changed, 92 insertions(+), 62 deletions(-)
diff --git a/base/changes.txt b/base/changes.txt
index 51e856dd..5ef00870 100644
--- a/base/changes.txt
+++ b/base/changes.txt
@@ -6,6 +6,20 @@ to completeness or accuracy and it contains some references to files that are
not part of the distribution.
================================================================================
+2023-11-14 Frank Mittelbach <Frank.Mittelbach at latex-project.org>
+
+ * ltmarks.dtx:
+ Some internal commands renamed and extended.
+
+ Generalized the support for extracting marks to cover cases like multicols.
+
+ Renamed \__mark_update_structure:nn to \__mark_update_structure_from_material:nn
+
+ Added \__mark_get_marks_for_reinsertion:nNN
+
+ Added \ShowMarksAt for debugging (might not stay this way)
+
+
2023-11-09 Yukai Chou <muzimuzhi at gmail.com>
* clsguide-historic.tex, usrguide.tex:
Replace quotation with quote envs for zero para indent
diff --git a/base/ltmarks.dtx b/base/ltmarks.dtx
index 32c0ab32..2f9f49d1 100644
--- a/base/ltmarks.dtx
+++ b/base/ltmarks.dtx
@@ -16,7 +16,7 @@
%
% \begin{macrocode}
\def\ltmarksversion{v1.0e}
-\def\ltmarksdate{2023/11/13}
+\def\ltmarksdate{2023/11/14}
% \end{macrocode}
%<*driver>
\documentclass{l3doc}
@@ -627,8 +627,8 @@
% \texttt{page} and \texttt{column} because only they have
% \texttt{previous-...} counterparts.
%
-% Another important aspect to keep in mind is that marks are only
-% recognized if they appear on top-level, e.g., if we want to
+% Another important aspect to keep in mind is that marks are recognized
+% only if they appear on the top level, e.g., if we want to
% process material stored in boxes we need to put it unboxed (using
% \cs{unvcopy} etc.)\ into the second argument.
% \end{function}
@@ -672,7 +672,7 @@
% does not update mark structures and can therefore be used outside
% the output routine as well.
%
-% It collect all marks inside the \meta{source} and adds suitable
+% It collect all the marks from inside the \meta{source} and adds suitable
% \cs{mark_insert:nn} in the two token lists. These token lists can
% then be executed at the right place to reinsert the marks, e.g.,
% directly after the box. This is, for example, used by
@@ -821,35 +821,42 @@
%
%
% \begin{macro}{\@@_extract_and_handle_marks:nnn}
+% \changes{v1.0e}{2023/11/14}{Macro added}
%
+% This is the main macro to extract and handle marks inside some
+% vertical material. It is used by
+% \cs{@@_update_structure_from_material:nn} (for updating the mark
+% structure for a region based on the marks found) and by
+% \cs{@@_get_marks_for_reinsertion:nNN} (for extracting marks from
+% some material and prepare for reinserting them later (e.g., out
+% of a box that is placed as a box into the main galley).
% \begin{macrocode}
\cs_new_protected:Npn \@@_extract_and_handle_marks:nnn #1#2#3 {
% \end{macrocode}
% This macro expects a region name as its third argument and
% vertical material (not boxed) as its fourth. It attempts to
-% extract mark information from \verb/#4/ and if it succeeds It
-% executes \verb/#1{#3}/ to do something with the marks, e.g., to
+% extract mark information from \verb/#3/ and, if it succeeds, it then
+% executes \verb/#1/ to do something with the marks, e.g., to
% update the mark structure for the region.
%
% If it finds infinite negative glue it generates an error message
-% and then calls \verb/#2{#3}/ to handle anything special in that
+% and then calls \verb/#2/ to handle anything special in that
% case.
%
% If it finds a forced break in the material it removes it and then
% restarts the attempt without it.
%
% Getting the first and last marks out of the material in \verb=#4=
-% is done by putting the material in a box and then doing a
-% split operation to the maximum size possible (which hopefully
-% means all of the content).\footnote{With normal column material cut
-% from the main galley we should always get all material in one go, but
-% in certain situations, for example,
-% in a \pkg{multicols} environment that contains
-% some \cs{columnbreak}s a single split operation will not be
-% enough. Thus, this this is something we need to handle.}
-% Because this is an action only for the sake of getting
-% at the mark values we don't want any underfull
-% box warnings so we turn those (locally) off.
+% is done by putting the material in a box and then doing a split
+% operation to the maximum size possible (which hopefully gets us
+% all of the content).\footnote{With normal column material cut
+% from the main galley we should always get all material in one go,
+% but in certain situations, for example, in a \pkg{multicols}
+% environment that contains some \cs{columnbreak}s a single split
+% operation will not be enough. Thus, this is something we need to
+% handle.} Because this action is used only to get the mark
+% values, we don't want any underfull box warnings so we (locally)
+% turn those off.
% \begin{macrocode}
\group_begin:
\dim_set_eq:NN \tex_splitmaxdepth:D \c_max_dim
@@ -872,14 +879,14 @@
% boxes end up as the last item on the page we should not unpack
% them.
%
-% All these issues need to be handled which is done in
+% All these issues need to be handled, which is done in
% \cs{@@_prepare_and_extract:nn}.
%
% \begin{macrocode}
\@@_prepare_and_extract:nnn {#1} {#2} {#3}
% \end{macrocode}
-% Once all mark classes have been processed the data structures are
-% updated and we can close the group which undoes our local
+% Once all mark classes have been processed, the data structures are
+% updated and we can close the group, which undoes our local
% changes and retains only the global ones.
% \begin{macrocode}
\group_end:
@@ -895,14 +902,14 @@
% \end{macrocode}
%
% To handle the \cs{enlargethispage} case we do an \tn{unskip} to
-% get rid of that glue if present and also check if we have then a
+% get rid of any glue that is present at the end and also check if we have then a
% \tn{vbox} as the last item and if so unpack that too, but only
% under certain conditions, see below. All this is temporary, just
% for getting the marks out, so it doesn't affect the final page
% production.
%
% In fact, we go one step further and set the box to a large
-% negative height possible and afterwards take a look at the
+% negative height and afterwards take a look at the
% reported badness: if it is zero we know that there has still been
% infinite shrinkage in the box so that we can't do a
% \tn{vsplit}. If that is the case we generate an error message and
@@ -919,9 +926,9 @@
\box_set_to_last:N \l_@@_box
% \end{macrocode}
% After having removed the last box from the current list (if there
-% was one) we check if the list is now empty. If not, the the last
+% was one) we check whether the list is now empty. If not, then the last
% box is definitely not the one from \tn{enlargethispage} and so we
-% can and should leave it alone. Otherwise we check if this last
+% can, and should, leave it alone. Otherwise we check if this last
% box is a \tn{vbox}.
% \changes{v1.0d}{2022/06/01}{Extend the logic for detecting the marks
% in the box (gh/836)}
@@ -931,9 +938,9 @@
\box_if_vertical:NT \l_@@_box
{
% \end{macrocode}
-% If it is, we do a further test and retypeset the \cs{l_@@_box}
-% to check if it contains infinitely shrinkable glue using the same
-% trick as before.
+% If it is, we do a further test and retypeset the \cs{l_@@_box} to
+% check whether it contains infinitely shrinkable glue, using the
+% same trick as before.
% \begin{macrocode}
\vbox_set_to_ht:Nnn \l_@@_box { -.5\c_max_dim }
{
@@ -942,10 +949,10 @@
% is not empty
}
% \end{macrocode}
-% If we don't detect infinite negative glue we unpack the box. If
-% yes we ignore it for the process of mark extraction. However, we
-% do not generate an error message, because in all likelihood this
-% is an ordinary box like a marginal that does contain something
+% If we don't detect infinite negative glue then we unpack the box. If
+% we do, we ignore it for the process of mark extraction. However, we
+% do not generate an error message because in all likelihood this
+% is an ordinary box, like a marginal, that does contain something
% like \tn{vss}.
% \begin{macrocode}
\int_compare:nNnT \tex_badness:D > 0
@@ -972,9 +979,8 @@
% didn't show any) we vsplit it. Note that it
% doesn't matter that we set it to this strange size first. If there
% was infinite shrinkage after all, we end up with a low-level
-% \TeX{} error, but if that is the case, it is a coding error
-% somewhere and needs
-% correcting.
+% \TeX{} error, but if that is the case then there is a coding error
+% somewhere and needs to be corrected.
% \begin{macrocode}
\vbox_set_split_to_ht:NNn \l_@@_ii_box \l_@@_box \c_max_dim
% \end{macrocode}
@@ -985,9 +991,9 @@
\box_if_empty:NTF \l_@@_box
{ #1 }
% \end{macrocode}
-% If we have a remainder after the split then this means that there was some forced
-% break in the material. We get rid of that be combining the
-% content of the two boxes and restart.
+% If we have a remainder after the split then this means that there
+% was some forced break in the material. We get rid of that by
+% combining the content of the two boxes and restart.
% \begin{macrocode}
{
%<*trace>
@@ -1014,6 +1020,8 @@
%
% \begin{macro}{\@@_update_structure_from_material:nn}
%
+% \changes{v1.0e}{2023/11/14}{Macro renamed}
+%
% This function updates the mark structures of a region. The first
% argument is the region to update and second argument receives the
% material that holds the marks. Out of this material we extract
@@ -1048,7 +1056,7 @@
\cs_new_protected:Npn \@@_update_structure_from_splitmarks:n #1 {
% \end{macrocode}
%
-% First thing we do is copying the current structure to
+% The first thing we do is to copy the current structure to
% \texttt{previous-...}; this leaves the current structure
% untouched so we can update it class by class (which is necessary).
% \begin{macrocode}
@@ -1081,8 +1089,8 @@
\tl_gset:No \g_@@_tmp_tl
{ \tex_splitbotmarks:D \use:c { c_@@_class_##1_mark } }
% \end{macrocode}
-% If this mark doesn't exist then obviously the first mark does
-% neither, so both become the last mark from the previous region. We
+% If this mark doesn't exist then obviously neither does the first mark,
+% so both become the last mark from the previous region. We
% have to be a little careful here: something like
% \verb=\mark_insert:nn{foo}{}= adds an \enquote{empty} mark that should
% not be confused with no mark at all. But no mark in our material
@@ -1148,9 +1156,9 @@
% \begin{macro}{\@@_get_marks_for_reinsertion:nNN}
%
% This function extracts the marks from the material in the first
-% argument but it does not update any the mark structure. Instead,
+% argument but it does not update any the mark structures. Instead,
% it collects the marks in the token lists given as the second and
-% third argument, in a way that they can be reinserted by just
+% third argument, in such a way that they can be reinserted by just
% executing the token lists.\footnote{It is probably enough to
% collect everything in a single token list as long as we put the
% first marks first and the last marks last). But for extra
@@ -1160,7 +1168,7 @@
% \begin{macrocode}
\cs_new_protected:Npn \@@_get_marks_for_reinsertion:nNN #1#2#3 {
% \end{macrocode}
-% First we clear the tmp token lists as we haven't seen any marks yet.
+% First we clear the temporary token lists as we haven't seen any marks yet.
% \begin{macrocode}
\tl_clear:N \g_@@_first_marks_tl
\tl_clear:N \g_@@_last_marks_tl
@@ -1172,13 +1180,13 @@
% \end{macrocode}
% If we can extract them (i.e., if we don't detect negative infinite
% glue) then this is done with \cs{@@_get_from_splitmarks:} otherwise
-% we issue warning that mark extraction was not possible.
+% we issue a warning that mark extraction was not possible.
% \begin{macrocode}
{ \@@_get_from_splitmarks: }
{ \msg_warning:nn { mark } { infinite-shrinkage-box } }
{ #1 }
% \end{macrocode}
-% finally we copy the updated (or not updated) tmp token lists to
+% Finally we copy the updated (or not updated) temporary token lists to
% the two that have been supplied when the function was called.
% By convention they are local variables and
% \cs{@@_extract_and_handle_marks:nnn} runs in a group, which is
@@ -1201,7 +1209,7 @@
\seq_map_inline:Nn \g_@@_classes_seq
{
% \end{macrocode}
-% First we to get the last last mark for the current class from the
+% First we to get the last mark for the current class from the
% material supplied.
% \begin{macrocode}
\tl_gset:No \g_@@_tmp_tl
@@ -1210,12 +1218,17 @@
%
% If this mark doesn't exist then obviously first mark doesn't
% either, so we do nothing (other than issuing some debugging
-% info). We have to be a little careful here: something like
+% info).
+
+% We have to be a little careful here: something like
% \verb=\mark_insert:nn{foo}{}= adds an \enquote{empty} mark that
-% should not be confused with no mark at all. But no mark in our
-% material will result in \cs{g_@@_tmp_tl} being fully empty. This
-% is why we have to make sure that \enquote{empty} from
-% \cs{mark_insert:nn} only appears to be empty but fails the next
+% we should not confuse with the case where there is no mark at
+% all.
+%
+% When there is no mark at all we get a truly empty
+% \cs{g_@@_tmp_tl} as a result. This is why we have to make sure
+% that an \enquote{empty} mark generated with \cs{mark_insert:nn}
+% only appears to be empty when it is typeset, but fails the next
% test (see below how this is done).
% \begin{macrocode}
\tl_if_empty:NTF \g_@@_tmp_tl
@@ -1241,7 +1254,7 @@
{ \mark_insert:nn {##1} { \g_@@_tmp_tl } }
% \end{macrocode}
% Because we had a last mark we also have a first mark (which might
-% be the same, but might be not), so we pick that up and add it to
+% be the same, but might not be), so we pick that up and add it to
% the \cs{g_@@_first_marks_tl} token list. This explains why we
% first checked for the last mark because that makes the processing
% faster in case there is none.
@@ -1268,7 +1281,7 @@
%
%
% \begin{macro}{\g_@@_first_marks_tl,\g_@@_last_marks_tl}
-% The two global variables used in the code above.
+% These are two global temporary variables used in the code above.
% \begin{macrocode}
\tl_new:N \g_@@_first_marks_tl
\tl_new:N \g_@@_last_marks_tl
@@ -1420,7 +1433,7 @@
% To retrieve the first, last or top region mark, we grab the
% appropriate value stored in the corresponding token list variable
% and pass its contents back. These functions should be used only
-% in output routines after \cs{@@_update_structure_from_material:nn} has acted,
+% in output routines and only after \cs{@@_update_structure_from_material:nn} has acted,
% otherwise their value will be wrong.
%
% If used with an unknown class or region they generate an error
@@ -1521,10 +1534,12 @@
}
% \end{macrocode}
%
-% If box content checked for marks contains some infinite negative glue
-% allowing it to shrink to an arbitrarily small size we can't extract any marks.
-% They are lost, but this should not generate an error because in
-% certain places, e.g., in some \env{minipage}s such glue might be legitimate.
+% If some arbitrary box content to be checked for marks contains
+% some infinite negative glue, allowing it to shrink to an
+% arbitrarily small size, then we can't extract any marks. They
+% are lost, but this should not generate an error because in
+% certain places, e.g., in some \env{minipage}s, such glue might be
+% legitimate.
% \begin{macrocode}
\msg_new:nnn { mark } { infinite-shrinkage-box }
{ Infinite~shrinkage~found~in~box~material~--~marks~not~extracted~
@@ -1644,12 +1659,13 @@
%
%
% \begin{macro}{\ShowMarksAt}
+% \changes{v1.0e}{2023/11/14}{Macro added}
% Debugging helper that displays a snapshot of all known mark
-% structures. The argument is a text string that this is
+% structures. The argument is a text string that is
% displayed to help identifying when the snapshot was made.
%
-% This may may not stay like this which is why it isn't yet
-% documented as an official command.
+% This may not stay like this (or at all), which is why it isn't
+% yet documented as an official command.
% \begin{macrocode}
\cs_new_protected:Npn \ShowMarksAt #1 {
%<*trace>
More information about the latex3-commits
mailing list.