summaryrefslogtreecommitdiff
path: root/macros/latex-dev/base/ltmarks.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex-dev/base/ltmarks.dtx')
-rw-r--r--macros/latex-dev/base/ltmarks.dtx656
1 files changed, 492 insertions, 164 deletions
diff --git a/macros/latex-dev/base/ltmarks.dtx b/macros/latex-dev/base/ltmarks.dtx
index 677534dd27..dcfa2fcb27 100644
--- a/macros/latex-dev/base/ltmarks.dtx
+++ b/macros/latex-dev/base/ltmarks.dtx
@@ -1,7 +1,7 @@
% \iffalse meta-comment
%
%% File: ltmarks.dtx
-%% Copyright (C) 2022-2023
+%% Copyright (C) 2022-2024
%% Frank Mittelbach, The LaTeX Project
%
% It may be distributed and/or modified under the conditions of the
@@ -14,12 +14,14 @@
%
%%% From File: ltmarks.dtx
%
-% \begin{macrocode}
-\def\ltmarksversion{v1.0d}
-\def\ltmarksdate{2022/06/01}
-% \end{macrocode}
%<*driver>
+% \fi
+\ProvidesFile{ltmarks.dtx}
+ [2024/02/11 v1.0e LaTeX Kernel (Marks)]
+% \iffalse
+%
\documentclass{l3doc}
+\GetFileInfo{ltmarks.dtx}
%\usepackage{ltmarks}
@@ -45,7 +47,7 @@
%
%
% \title{The \texttt{ltmarks.dtx} code\thanks{This file has version
-% \ltmarksversion\ dated \ltmarksdate, \copyright\ \LaTeX\
+% \fileversion\ dated \filedate, \copyright\ \LaTeX\
% Project.}}
% \author{^^A
% Frank Mittelbach, \LaTeX{} Project\thanks
@@ -156,7 +158,7 @@
% \begin{function}{\InsertMark,\mark_insert:nn}
% \begin{syntax}
% \cs{InsertMark} \Arg{class} \Arg{text}
-% \cs{mark_insert:nn} \Arg{class} \Arg{text}
+% \cs{mark_insert:nn} \Arg{class} \Arg{text}
% \end{syntax}
% Adds a mark to the current galley for the \meta{class}, containing the
% \meta{text}.
@@ -299,6 +301,8 @@
% \emph{true}; if a declared and an undeclared mark class is used
% it is always \emph{false}.}
%
+% \subsection{Use cases for conditionals}
+%
% However, the basic version is enough for the following typical use cases:
% \begin{description}
% \item[Test for at most one mark of class \texttt{myclass} on current
@@ -353,7 +357,7 @@
% \begin{function}{\DebugMarksOn,\DebugMarksOff,
% \mark_debug_on:,\mark_debug_off:}
% \begin{syntax}
-% \cs{DebugMarksOn} ... \cs{DebugMarksOff}
+% \cs{DebugMarksOn} \ldots\ \cs{DebugMarksOff}
% \end{syntax}
%
% Commands to turn the debugging of mark code on or off. The
@@ -397,8 +401,8 @@
%
% \begin{function}{\markboth, \markright}
% \begin{syntax}
-% \cs{markboth} \Arg{left} \Arg{right}
-% \cs{markright} \Arg{right}
+% \cs{markboth} \Arg{left} \Arg{right}
+% \cs{markright} \Arg{right}
% \end{syntax}
% \LaTeXe{} uses two marks which aren't fully independent. A
% \enquote{left} mark generated by the first argument of \cs{markboth}
@@ -610,9 +614,9 @@
% marks. It too is called as part of \cs{@opcol}.
% \end{function}
%
-% \begin{function}{\@@_update_structure:nn}
+% \begin{function}{\@@_update_structure_from_material:nn}
% \begin{syntax}
-% \cs{@@_update_structure:nn} \Arg{region} \Arg{material with marks}
+% \cs{@@_update_structure_from_material:nn} \Arg{region} \Arg{material with marks}
% \end{syntax}
% Helper function that inspects the marks
% inside the second argument and assigns new mark values based on
@@ -627,8 +631,8 @@
% \texttt{page} and \texttt{column} because only they have
% \texttt{previous-...} counterparts.
%
-% Another important part 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}
@@ -642,7 +646,7 @@
% Helper function that copies all mark values in the \meta{source}
% region to \meta{alias}, i.e., make the structures identical. Used
% to update the \texttt{previous-...} structures inside
-% \cs{@@_update_structure:nn} and \texttt{first-column} and
+% \cs{@@_update_structure_from_material:nn} and \texttt{first-column} and
% \texttt{last-column} structures inside
% \cs{@@_update_singlecol_structures:} or
% \cs{@@_update_dblcol_structures:}.
@@ -650,7 +654,6 @@
%
%
%
-%
% \begin{function}{\@@_update_structure_to_err:n}
% \begin{syntax}
% \cs{@@_update_structure_to_err:n} \Arg{region}
@@ -662,6 +665,37 @@
% \end{function}
%
%
+% \begin{function}{\@@_get_marks_for_reinsertion:nNN}
+% \begin{syntax}
+% \cs{@@_get_marks_for_reinsertion:nNN} \Arg{source}
+% \qquad \meta{token-list-var for collecting first marks}
+% \qquad \meta{token-list-var for collecting last marks}
+% \end{syntax}
+% Helper function for extracting marks that would otherwise get
+% lost, for example when they are hidden inside a box. This helper
+% does not update mark structures and can therefore be used outside
+% the output routine as well.
+%
+% It collect all the top-level 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 \pkg{multicol} when a short balanced
+% \env{multicols} is returned to the galley for typesetting.
+%
+% If the \meta{source} consists of a single vertical box (plus
+% possibly followed by some glue but nothing else) then the box is
+% unpacked and the top-level marks are collected from its
+% content. However, if it is not a vertical box or there are are
+% other data then nothing is unpacked and you have to do the
+% unpacking yourself to get at the marks inside.
+%
+% It is quite likely that one only needs a single token list for
+% returning the \cs{mark_insert:nn} statements. If that is the case
+% this command may change to take only two arguments.
+% \end{function}
+%
+%
%
% ^^A \end{documentation}
%
@@ -703,12 +737,13 @@
%
%
% \begin{macro}{\mark_new_class:n,\@@_new_class:nn}
+%
% A mark class is created by initializing a number of data
-% structures. First, we get a register number to refer to the mark class.
-% The new mark class is then added to the \cs{g_@@_classes_seq}
-% sequence to be able to easily loop over all classes. Finally a
-% number of top-level global token lists are declared that hold
-% various versions of the mark for access.
+% structures. First, we get a register number to refer to the mark
+% class. The new mark class is then added to the
+% \cs{g_@@_classes_seq} sequence to be able to easily loop over all
+% classes. Finally a number of top-level global token lists are
+% declared that hold various versions of the mark for access.
% \begin{macrocode}
\cs_new_protected:Npn \mark_new_class:n #1
{
@@ -784,57 +819,74 @@
% \subsection{Updating mark structures}
%
%
-% \begin{macro}{\l_@@_box,\g_@@_tmp_tl,\g_@@_new_top_tl}
-% For some operations we need a temporary private box and two
+% \begin{macro}{\l_@@_box,\l_@@_ii_box,\g_@@_tmp_tl,\g_@@_new_top_tl}
+% For some operations we need two temporary private boxes and two
% private global token lists.
% \begin{macrocode}
\box_new:N \l_@@_box
+\box_new:N \l_@@_ii_box
\tl_new:N \g_@@_tmp_tl
\tl_new:N \g_@@_new_top_tl
% \end{macrocode}
% \end{macro}
%
%
-% \begin{macro}{\@@_update_structure:nn}
-%
-% This function updates the mark structures. The first argument is
-% the region to update and second argument receives the material
-% that holds the marks. Out of this material we extract the first
-% and last marks for all classes (if there are any) to do the
-% assignments.
%
+% \begin{macro}{\@@_extract_and_handle_marks:nn}
+% \changes{v1.0e}{2024/01/29}{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 \@@_update_structure:nn #1#2
- {
+\cs_new_protected:Npn \@@_extract_and_handle_marks:nn #1#2 {
% \end{macrocode}
-% First thing we do is copying the current structure to
-% \texttt{previous-...}; this leaves the current structure
-% untouched so we can update it class by class (which is necessary).
+% This macro expects code to handle extracted marks in its first argument and
+% vertical material (not boxed or just consisting of a single
+% vertical box) as its second. It
+% extracts top-level mark information from \verb/#2/, stores them
+% as split marks and then calls
+% \verb/#1/ to make use of this information.
+%
+% If it finds a forced break in the material it removes it and then
+% restarts the attempt without it.
+%
+% We start with a group to keep most changes local.
% \begin{macrocode}
- \@@_update_structure_alias:nn { previous-#1 } {#1}
+ \group_begin:
% \end{macrocode}
+%
% Getting the first and last marks out of the material in \verb=#2=
-% 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{We could verify this, maybe we
-% should.} 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
\int_set_eq:NN \tex_vbadness:D \c_max_int
\dim_set_eq:NN \tex_vfuzz:D \c_max_dim
% \end{macrocode}
-% There is a further complication: if the region contains infinite
+%
+% There is a further complication: if the material contains infinite
% shrinking glue then a \tn{vsplit} operation will balk with a
-% low-level error. Now pages or columns, which are our main concern here, can't
-% have such infinite shrinkage if they are cut straight from the
-% galley, however the use of \tn{enlargethispage} actually does add
-% some at the very bottom (and also wraps the whole page into a box
-% by itself, so if we leave it this way then a) we get this error
-% and b) we don't see any marks because they are hidden one level
-% down).
+% low-level error. Now pages or columns, which are our main concern
+% here, can't have such infinite shrinkage if they are cut straight
+% from the galley, however the use of \tn{enlargethispage} actually
+% does add some at the very bottom (and also wraps the whole page
+% into a box by itself, so if we leave it this way then a) we get
+% this error and b) we don't see any marks because they are hidden
+% one level down).
%
% Another possible issue are packages or user code that place stray
% \tn{vbox}es directly into the main galley (an example is
@@ -842,93 +894,236 @@
% boxes end up as the last item on the page we should not unpack
% them.
%
-% We therefore do an \tn{unskip} to get rid of that glue if present 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
-% 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
-% bypass extracting the marks. We use only half of \cs{c_max_dim}
-% because otherwise \TeX{} will report an overfull vbox despite our
-% setting of \cs{tex_vfuzz:D}. This test will not find existing
-% infinite shrinkage in all cases, e.g., if there are several glues
-% that cancel each other, but it is the best we can do.
-% \begin{macrocode}
- \vbox_set_to_ht:Nnn \l_@@_box { -.5\c_max_dim }
- {
- #2
- \tex_unskip:D
- \box_set_to_last:N \l_@@_box
+% All these issues need to be handled, which is done in
+% \cs{@@_prepare_and_extract:nn}.
+%
+% \begin{macrocode}
+ \@@_prepare_and_extract:nn {#1} {#2}
+% \end{macrocode}
+% 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:
+ }
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\@@_prepare_and_extract:nn}
+%
+% This macro does the dirty work. It is not directly integrated in
+% \cs{@@_extract_and_handle_marks:nn} because we may have to call
+% it recursively if we find forced breaks.
+% \begin{macrocode}
+\cs_new_protected:Npn \@@_prepare_and_extract:nn #1#2 {
+% \end{macrocode}
+%
+% To handle the \cs{enlargethispage} case we do an \tn{unskip} to
+% get rid of any glue that is present at the very end of the material
+% 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 done in a group, just for getting
+% the marks out, so it doesn't affect the final page production.
+%
+% \begin{macrocode}
+ \vbox_set:Nn \l_@@_box
+ {
+ #2
+ \tex_unskip:D
+ \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 box is
-% definitely not the one from \tn{enlargethispage} and so we can
-% and should leave it alone. Otherwise we check if this last box is
-% a \tn{vbox}.
+% was one) we check whether the vertical 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 box is a \tn{vbox}.
% \changes{v1.0d}{2022/06/01}{Extend the logic for detecting the marks
% in the box (gh/836)}
% \begin{macrocode}
- \int_compare:nNnT \tex_lastnodetype:D < 0
- {
- \box_if_vertical:NT \l_@@_box
- {
-% \end{macrocode}
-% If it is we do a further test and reset the \cs{l_@@_box}
-% to check if it contains infinitely shrinkable glue.
-% \begin{macrocode}
- \vbox_set_to_ht:Nnn \l_@@_box { -.5\c_max_dim }
- {
- \vbox_unpack:N \l_@@_box
- \tex_kern:D \c_zero_dim % ensure that box
- % is not empty
- }
+ \int_compare:nNnT \tex_lastnodetype:D < 0
+ {
+ \box_if_vertical:NT \l_@@_box
% \end{macrocode}
-% If not, then we unpack it, if yes we still ignore it for the process of
-% mark extraction. We do not generate an error though, because in all
-% likelihood this is an ordinary box like a marginal that does
-% contain something like \tn{vss}.
+% If it is, we unpack the box.
% \begin{macrocode}
- \int_compare:nNnT \tex_badness:D > 0
- { \vbox_unpack:N \l_@@_box }
- }
- }
+ { \vbox_unpack:N \l_@@_box }
+ }
% \end{macrocode}
% If it wasn't a vbox, it was either an hbox or there was no box.
% Given that we are only interested in the marks we don't need put
-% it back in that case. However, we have to make sure that the
-% outer box under construction
-% is not totally empty (which it might have been from the start, or
-% now), because \TeX{} does not report a badness for empty boxes
-% and that means our test would incorrectly conclude that we have
-% infinite shrinking glue. A simple \tn{kern} is enough to avoid
-% this (the same was already done above).
-% \begin{macrocode}
- \tex_kern:D \c_zero_dim
- }
- \int_compare:nNnTF \tex_badness:D > 0
+% it back in that case.
+% \begin{macrocode}
+ }
% \end{macrocode}
-% If the box had no infinite shrinkage (or rather if our test
-% 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 there is, it is a coding error and needs
-% correcting.
+% We are now ready to \cs{vsplit} the box to get at the marks. If
+% the box contains some infinite negative glue the \TeX{} will
+% produce an error complaining about it but it will correctly find
+% the the split marks. Given that we can't prevent that error, we
+% hide it from the user and ensure that \TeX{} doesn't stop. The
+% error message still shows in the log, but even that is mitigated
+% as best as possible---see the definition of
+% \cs{@@_vbox_set_split_to_maxdimen:NN} for the tricks employed.
% \begin{macrocode}
- {
- \vbox_set_split_to_ht:NNn \l_@@_box \l_@@_box \c_max_dim
+ \@@_vbox_set_split_to_maxdimen:NN \l_@@_ii_box \l_@@_box
+% \end{macrocode}
+% After splitting we check if there is anything left in
+% \cs{l_@@_box}. If not then the above split has set some split marks
+% that we can then use to finish the extraction:
+% \begin{macrocode}
+ \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 by
+% combining the content of the two boxes and restart.
+% \begin{macrocode}
+ {
+%<*trace>
+ \@@_debug:n { \iow_term:x
+ { Marks:~ mark~ extraction~needs~ recursion~
+ \msg_line_context: } }
+%</trace>
+ \@@_prepare_and_extract:nn {#1}
+ { \vbox_unpack:N \l_@@_ii_box
+ \vbox_unpack:N \l_@@_box }
+ }
+}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\@@_vbox_set_split_to_maxdimen:NN}
+%
+% Split a box to get at its marks without pausing even if \TeX{} is
+% producing an error message because of infinite negative glue in
+% the box. If there is such an error we ensure that it only shows
+% up in the log but not on the terminal.
+%
+% The nice low-level hack by DPC records in the \texttt{.log} that a glue
+% shrinkage error is harmless.
+%
+% We disguise \cs{c_max_dim} in an odd looking csname, which then
+% shows up as part of the display of an error message if that error
+% happens. This csname forms part of the error diplay so what
+% you get is something like
+%\begin{verbatim}
+% ! Infinite glue shrinkage found in box being split.
+% <argument> Infinite shrink error above ignored !
+% l. ... }
+%\end{verbatim}
+% which hopefully makes it clear that the error is harmless and
+% and should be ignored by the reader of the \texttt{.log}.
+% \begin{macrocode}
+\cs_set_eq:cN {Infinite~shrink~error~above~ignored~!}\c_max_dim
+% \end{macrocode}
+%
+% The whole definition of \cs{@@_vbox_set_split_to_maxdimen:NN}
+% below is fully expanded, so we have to use a lot of
+% \cs{exp_not:N} commands to prevent expansion where necessary.
+% \begin{macrocode}
+\cs_new_protected:Npx \@@_vbox_set_split_to_maxdimen:NN #1#2 {
+% \end{macrocode}
+% We start by saving the current interaction and escape char settings.
+% \begin{macrocode}
+ \tl_set:Ne \exp_not:N \l_@@_saved_parameters_tl
+ {
+ \tex_interactionmode:D
+ \exp_not:N \int_use:N \tex_interactionmode:D \scan_stop:
+ \tex_escapechar:D
+ \exp_not:N \int_use:N \tex_escapechar:D \scan_stop:
+ }
+% \end{macrocode}
+% Then we change them so that no escape char is printed in the
+% error message (accounts for the missing backslash in front of
+% \verb/Infinite shrink .../) and we set the interaction to
+% \cs{nonstopmode} so that the the error (if any) just goes into
+% the \texttt{.log} file and \TeX{} doesn't stop at that point.
+% \begin{macrocode}
+ \tex_escapechar:D -1 \scan_stop:
+ \tex_interactionmode:D 0 \scan_stop:
+% \end{macrocode}
+% Then we do the splitting of the box to \cs{c_max_dim} to get at
+% the marks. This may generate the error we are worried about,
+% i.e., if the box contains infinite negative glue. However, \TeX{}
+% makes this glue finite and continues, which means we get our split
+% marks which is really all we care about.
+% \begin{macrocode}
+ \tex_setbox:D #1 \tex_vsplit:D #2 to
+% \end{macrocode}
+% The \cs{use:n} may seem pointless, and it is to some extent, but
+% we need it to get our disguised \cs{c_max_dim} displayed
+% properly as part of the error message if there is one. Without
+% it, the display would show only part of what we want it to show
+% (try it).
+% \begin{macrocode}
+ \exp_not:N \use:n {
+ \use:c{Infinite~shrink~error~above~ignored~!}
+ }
+% \end{macrocode}
+% Finally, we change the escape char and the interaction mode back
+% to what it was before:
+% \begin{macrocode}
+ \exp_not:N \l_@@_saved_parameters_tl
+}
+% \end{macrocode}
+% \end{macro}
+%
+%
+%
+% \begin{macro}{\l_@@_saved_parameters_tl}
+% The temporary variable used for resetting escape char and
+% interaction mode.
+% \begin{macrocode}
+\tl_new:N \l_@@_saved_parameters_tl
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\@@_update_structure_from_material:nn}
+%
+% \changes{v1.0e}{2024/01/29}{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
+% the first and last marks for all classes (if there are any) to do
+% the assignments.
+%
+% \begin{macrocode}
+\cs_new_protected:Npn \@@_update_structure_from_material:nn #1#2 {
+ \@@_extract_and_handle_marks:nn
+% \end{macrocode}
+%
+% Once the marks can be extracted we update the structure from the
+% split marks (code in \cs{@@_update_structure_from_splitmarks:n}).
+% \begin{macrocode}
+ { \@@_update_structure_from_splitmarks:n {#1} }
+ { #2 }
+}
+% \end{macrocode}
+% \end{macro}
+%
+%
+%
+% \begin{macro}{\@@_update_structure_from_splitmarks:n}
+% This macro is called after we have done a \cs{tex_vsplit:D}
+% operation and the mark data is in the split marks.
+% \begin{macrocode}
+\cs_new_protected:Npn \@@_update_structure_from_splitmarks:n #1 {
+% \end{macrocode}
+%
+% The first thing we do is to copy the current region structure to
+% \texttt{previous-...}; this leaves the current structure
+% untouched so we can update it class by class (which is necessary).
+% \begin{macrocode}
+ \@@_update_structure_alias:nn { previous-#1 } {#1}
% \end{macrocode}
% After this action we can get first and last marks of the various
% classes through \cs{tex_splitfirstmarks:D} and
% \cs{tex_splitbotmarks:D}. So now we loop over all classes stored in
% \cs{g_@@_classes_seq}.
% \begin{macrocode}
- \seq_map_inline:Nn \g_@@_classes_seq
+ \seq_map_inline:Nn \g_@@_classes_seq
{
% \end{macrocode}
% First action: get the last mark from the previous region, i.e.,
@@ -950,14 +1145,14 @@
\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 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
% 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 test (see below how this
+% appears to be empty when typeset but fails the next test (see below how this
% is done).
% \begin{macrocode}
\tl_if_empty:NTF \g_@@_tmp_tl
@@ -987,29 +1182,144 @@
}
}
}
- }
+}
+% \end{macrocode}
+% \end{macro}
+%
+%
+%
+% \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 structures. Instead,
+% it collects the marks in the token lists given as the second and
+% 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
+% flexibility, I currently use 2 token lists. This might change when it is
+% really clear that this is never needed.}
+%
+% \begin{macrocode}
+\cs_new_protected:Npn \@@_get_marks_for_reinsertion:nNN #1#2#3 {
% \end{macrocode}
-% If the badness was zero (we actually tested for${}>0$ but it
-% can't get negative) then we had infinite shrinkage, so we report
-% that and set all marks to the value the last mark had before.
+% First we clear the temporary token lists as we haven't seen any marks yet.
% \begin{macrocode}
- {
- \msg_error:nnn { mark } { infinite-shrinkage } {#1}
- \seq_map_inline:Nn \g_@@_classes_seq
+ \tl_clear:N \g_@@_first_marks_tl
+ \tl_clear:N \g_@@_last_marks_tl
+% \end{macrocode}
+% Then we extract all top-level marks, thereby filling the token lists
+% with suitable \cs{mark_insert:nn} calls.
+% \begin{macrocode}
+ \@@_extract_and_handle_marks:nn
+% \end{macrocode}
+% The first argument holds the code for fill the token lists and
+% the second is the material we extract from.
+% \begin{macrocode}
+ \@@_get_from_splitmarks:
+ { #1 }
+% \end{macrocode}
+%
+% 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 \enquote{get} operations return their
+% values in local variables and \cs{@@_extract_and_handle_marks:nn}
+% runs in a group, which is why we have to use global temporary
+% variables for collecting.
+% \begin{macrocode}
+ \tl_set_eq:NN #2 \g_@@_first_marks_tl
+ \tl_set_eq:NN #3 \g_@@_last_marks_tl
+}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\@@_get_from_splitmarks:}
+% This function is called after we have done a \cs{vsplit} to
+% update the split marks. It loops through all mark classes to find
+% out if there are marks for this class and if so updates the
+% global tls used for collecting.
+% \begin{macrocode}
+\cs_new_protected:Npn \@@_get_from_splitmarks: {
+ \seq_map_inline:Nn \g_@@_classes_seq
{
- \tl_gset_eq:cc { g_@@_#1_top_ ##1_tl }
- { g_@@_#1_last_ ##1_tl }
- \tl_gset_eq:cc { g_@@_#1_first_##1_tl }
- { g_@@_#1_last_ ##1_tl }
+% \end{macrocode}
+% First we to get the last mark for the current class from the
+% material supplied.
+% \begin{macrocode}
+ \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 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
+% \verb=\mark_insert:nn{foo}{}= adds an \enquote{empty} mark that
+% 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
+ {
+%<*trace>
+ \@@_debug:n { \iow_term:x { Marks:~no~ marks~
+ for~ class~ '##1'~\msg_line_context: } }
+%</trace>
+ }
+% \end{macrocode}
+%
+% If it wasn't empty, i.e., if it had a real value then we use this
+% value for our new last mark instead. This means we put an
+% appropriate \cs{mark_insert:nn} statement into
+% \cs{g_@@_last_marks_tl}.
+% \begin{macrocode}
+ {
+%<*trace>
+ \@@_debug:n { \iow_term:x { Marks:~ extract~ last~
+ mark~ for~ class~ '##1'~ =~ \g_@@_tmp_tl } }
+%</trace>
+ \tl_gput_right:Ne \g_@@_last_marks_tl
+ { \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 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.
+% \begin{macrocode}
+%<*trace>
+ \@@_debug:n { \iow_term:x { Marks:~ extract~ first~
+ mark~ for~ class~ '##1'~ =~
+ \tex_splitfirstmarks:D
+ \use:c { c_@@_class_##1_mark }
+ } }
+%</trace>
+ \tl_gput_right:Ne \g_@@_first_marks_tl
+ { \mark_insert:nn {##1}
+ {
+ \tex_splitfirstmarks:D
+ \use:c { c_@@_class_##1_mark }
+ }
+ }
+ }
}
- }
+}
% \end{macrocode}
-% 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.
+% \end{macro}
+%
+%
+% \begin{macro}{\g_@@_first_marks_tl,\g_@@_last_marks_tl}
+% These are two global temporary variables used in the code above.
% \begin{macrocode}
- \group_end:
- }
+\tl_new:N \g_@@_first_marks_tl
+\tl_new:N \g_@@_last_marks_tl
% \end{macrocode}
% \end{macro}
%
@@ -1158,7 +1468,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: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
@@ -1207,7 +1517,7 @@
%
% \subsection{Messages}
%
-% Mark errors are LaTeX kernel errors:
+% Mark errors are \LaTeX{} kernel errors:
% \changes{v1.0d}{2022/06/01}{Marks are kernel errors}
% \begin{macrocode}
\prop_gput:Nnn \g_msg_module_type_prop { mark } { LaTeX }
@@ -1247,17 +1557,7 @@
}
% \end{macrocode}
%
-% \begin{macrocode}
-\msg_new:nnnn { mark } { infinite-shrinkage }
- { Infinite~shrinkage~found~in~'#1'. }
- {
- \c__msg_coding_error_text_tl
- The~mark~region~'#1'~contains~some~infinite~negative~glue~
- allowing~it~to~shrink~to~an~arbitrary~size.~
- This~makes~it~impossible~to~split~the~region~apart~to~
- get~at~its~marks.~They~are~lost.
- }
-% \end{macrocode}
+%
%
%
%
@@ -1358,7 +1658,7 @@
%
%
% \begin{macro}{\@@_status:n}
-% Show all mark class values across all regions.
+% Show a snapshot of all mark class values across all regions.
% \begin{macrocode}
\cs_new_protected:Npn \@@_status:n #1
{
@@ -1370,6 +1670,22 @@
% \end{macro}
%
%
+% \begin{macro}{\ShowMarksAt}
+% \changes{v1.0e}{2024/01/29}{Macro added}
+% Debugging helper that displays a snapshot of all known mark
+% structures. The argument is a text string that is
+% displayed to help identifying when the snapshot was made.
+%
+% 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>
+ \@@_debug:n { \@@_status:n {#1} }
+%</trace>
+}
+% \end{macrocode}
+% \end{macro}
%
%
% \subsection{Designer-level interfaces}
@@ -1425,9 +1741,9 @@
%
%
%
-% \section{\LaTeXe{} integration}
+% \section{\LaTeXe{} integration}
%
-% \subsection{Core \LaTeXe{} integration}
+% \subsection{Core \LaTeXe{} integration}
%
% \begin{macro}{\@@_update_singlecol_structures:}
% This command updates the mark structures if we are producing a
@@ -1445,11 +1761,11 @@
% \begin{macrocode}
\box_if_vertical:NTF \@outputbox
{
- \@@_update_structure:nn {page}
+ \@@_update_structure_from_material:nn {page}
{ \vbox_unpack:N \@outputbox }
}
{
- \@@_update_structure:nn {page}
+ \@@_update_structure_from_material:nn {page}
{ \hbox_unpack:N \@outputbox }
}
% \end{macrocode}
@@ -1489,11 +1805,11 @@
% \begin{macrocode}
\box_if_vertical:NTF \@outputbox
{
- \@@_update_structure:nn {column}
+ \@@_update_structure_from_material:nn {column}
{ \vbox_unpack:N \@outputbox }
}
{
- \@@_update_structure:nn {column}
+ \@@_update_structure_from_material:nn {column}
{ \hbox_unpack:N \@outputbox }
}
% \end{macrocode}
@@ -1583,17 +1899,26 @@
%<@@=>
% \end{macrocode}
%
-% \begin{macro}[int]{\@expl@@@mark@update@singlecol@structures@@,
-% \@expl@@@mark@update@dblcol@structures@@}
+% \begin{macro}[int]{\@expl@@@mark@update@singlecol@structures@@}
% \begin{macrocode}
\cs_new_eq:NN \@expl@@@mark@update@singlecol@structures@@
\__mark_update_singlecol_structures:
+% \end{macrocode}
+% \end{macro}
+%
+%
+%
+% \begin{macro}[int]{\@expl@@@mark@update@dblcol@structures@@}
+% \begin{macrocode}
\cs_new_eq:NN \@expl@@@mark@update@dblcol@structures@@
\__mark_update_dblcol_structures:
% \end{macrocode}
% \end{macro}
%
-% \subsection{Other \LaTeXe{} output routines}
+%
+%
+%
+% \subsection{Other \LaTeXe{} output routines}
%
% This section will cover \pkg{multicol} and other packages altering
% or providing their own output routine. Not done yet.
@@ -1601,6 +1926,9 @@
%
%
%
+% \subsection{Rollback information}
+%
+%
% \begin{macrocode}
%<latexrelease>\IncludeInRelease{0000/00/00}{ltmarks}%
%<latexrelease> {Undo~Marks~handling}
@@ -1609,7 +1937,7 @@
% We keep the interface commands around even if we roll back in
% case they are used in packages that don't roll back. Not likely
% to do a lot of good, but then there is not much we can do, but
-% this at least then doesn't give errors.
+% this at least they won't give unknown csname errors.
% \begin{macrocode}
%<latexrelease>\DeclareRobustCommand \NewMarkClass[1]{}
%<latexrelease>\DeclareRobustCommand \InsertMark[2]{}