diff options
Diffstat (limited to 'macros/latex-dev/base/ltmarks.dtx')
-rw-r--r-- | macros/latex-dev/base/ltmarks.dtx | 656 |
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]{} |