[latex3-commits] [latex3/latex2e] ltmarks-multicol: make relevant mark functions for packages public (8e4feff4d)
github at latex-project.org
github at latex-project.org
Sun Nov 17 19:30:05 CET 2024
Repository : https://github.com/latex3/latex2e
On branch : ltmarks-multicol
Link : https://github.com/latex3/latex2e/commit/8e4feff4d8d3967293e44cf67ad53697bc1b7697
>---------------------------------------------------------------
commit 8e4feff4d8d3967293e44cf67ad53697bc1b7697
Author: Frank Mittelbach <frank.mittelbach at latex-project.org>
Date: Sun Nov 17 19:30:05 2024 +0100
make relevant mark functions for packages public
>---------------------------------------------------------------
8e4feff4d8d3967293e44cf67ad53697bc1b7697
base/changes.txt | 10 +++
base/ltmarks.dtx | 162 +++++++++++++++++++++++---------------------
required/tools/multicol.dtx | 26 +++----
3 files changed, 109 insertions(+), 89 deletions(-)
diff --git a/base/changes.txt b/base/changes.txt
index d49117328..accb411d6 100644
--- a/base/changes.txt
+++ b/base/changes.txt
@@ -6,6 +6,16 @@ to completeness or accuracy and it contains some references to files that are
not part of the distribution.
================================================================================
+2024-11-17 Frank Mittelbach <Frank.Mittelbach at latex-project.org>
+
+ * ltmarks.dtx (section{Public interfaces for packages such as \pkg{multicol}}):
+ Make all relevant functions public:
+ \mark_update_structure_from_material:nn
+ \mark_copy_structure:nn
+ \mark_set_structure_to_err:n
+ \mark_clear_structure:n
+ \mark_get_marks_for_reinsertion:nNN
+
2024-11-16 Frank Mittelbach <Frank.Mittelbach at latex-project.org>
* latex209.dtx:
diff --git a/base/ltmarks.dtx b/base/ltmarks.dtx
index cfada0429..829b5324b 100644
--- a/base/ltmarks.dtx
+++ b/base/ltmarks.dtx
@@ -698,52 +698,21 @@
% be taken care of---those are discussed in the implementation sections.
%
%
-% \section{Internal functions for \LaTeX's standard output routine and \pkg{multicol}}
%
-% The functions in this section are tied to the output routine and used in the
-% interface to \LaTeXe{} and perhaps at some later time within a new
-% output routine
-% for \LaTeX. They are not (yet) meant for general use and are
-% therefore made internal, even though we already use them in
-% \pkg{multicol}.
-% Internal means that \verb|@@| automatically gets
-% replaced in the code (and in the documentation) so we have to give
-% it a suitable value.
-% \begin{macrocode}
-%<@@=mark>
-% \end{macrocode}
-%
-% \begin{function}{\@@_update_singlecol_structures:}
-% \begin{syntax}
-% \cs{@@_update_singlecol_structures:}
-% \end{syntax}
-% \LaTeXe{} integration function in case we are doing single column
-% layouts. It assumes that the page content is already stored in
-% \cs{@outputbox} and processes the marks inside that box. It is
-% called as part of \cs{@opcol}.
-% \end{function}
%
+% \section{Public interfaces for packages such as \pkg{multicol}}
%
-% \begin{function}{\@@_update_dblcol_structures:}
-% \begin{syntax}
-% \cs{@@_update_singlecol_structures:}
-% \end{syntax}
-% \LaTeXe{} integration function mark used when we are doing double
-% column documents. It assumes that the page content is already
-% stored in \cs{@outputbox} and processes the marks inside that
-% box. It then does different post-processing depending on the start
-% of the switch \cs{if at firstcolumn}. If we are in the second column
-% it also has to update page marks, otherwise it only updates column
-% marks. It too is called as part of \cs{@opcol}.
-% \end{function}
+% The function in this section are public so that packages can make
+% use of them. However, this has to happen with great care, e.g.,
+% \cs{mark_update_structure_from_material:nn} updates the global mark
+% structure and can therefore be used only in in places where such an
+% update is meaningful, e.g., in special output routines. Elsewhere, a
+% change to the mark structure would break the whole mechanism and
+% querying the marks would return incorrect data.
%
-% \subsection{Candidates for a public interface}
-%
-% The remaining functions in this section may get a public interface eventually.
-%
-% \begin{function}{\@@_update_structure_from_material:nn}
+% \begin{function}{\mark_update_structure_from_material:nn}
% \begin{syntax}
-% \cs{@@_update_structure_from_material:nn} \Arg{region} \Arg{material with marks}
+% \cs{mark_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
@@ -766,14 +735,14 @@
%
%
%
-% \begin{function}{\@@_copy_structure:nn}
+% \begin{function}{\mark_copy_structure:nn}
% \begin{syntax}
-% \cs{@@_copy_structure:nn} \Arg{alias} \Arg{source}
+% \cs{mark_copy_structure:nn} \Arg{alias} \Arg{source}
% \end{syntax}
% 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_from_material:nn} and \texttt{first-column} and
+% \cs{mark_update_structure_from_material:nn} and \texttt{first-column} and
% \texttt{last-column} structures inside
% \cs{@@_update_singlecol_structures:} or
% \cs{@@_update_dblcol_structures:}.
@@ -781,9 +750,9 @@
%
%
%
-% \begin{function}{\@@_set_structure_to_err:n}
+% \begin{function}{\mark_set_structure_to_err:n}
% \begin{syntax}
-% \cs{@@_set_structure_to_err:n} \Arg{region}
+% \cs{mark_set_structure_to_err:n} \Arg{region}
% \end{syntax}
% Helper function that sets all mark values in the \meta{region} to
% an error message. This is currently used for \texttt{last-column}
@@ -791,9 +760,11 @@
% when we have just processed the first column in a two-column document.
% \end{function}
%
-% \begin{function}{\@@_clear_structure:n}
+%
+%
+% \begin{function}{\mark_clear_structure:n}
% \begin{syntax}
-% \cs{@@_clear_structure:n} \Arg{region}
+% \cs{mark_clear_structure:n} \Arg{region}
% \end{syntax}
% Helper function that sets all mark values in the \meta{region} to
% empty. This is currently used for \texttt{column} when a multicol
@@ -804,9 +775,9 @@
% \end{function}
%
%
-% \begin{function}{\@@_get_marks_for_reinsertion:nNN}
+% \begin{function}{\mark_get_marks_for_reinsertion:nNN}
% \begin{syntax}
-% \cs{@@_get_marks_for_reinsertion:nNN} \Arg{source}
+% \cs{mark_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}
@@ -836,6 +807,45 @@
% \end{function}
%
%
+% \section{Internal functions for the standard output routine of \LaTeX{}}
+%
+% The functions in this section are tied to the output routine and used in the
+% interface to \LaTeXe{} and perhaps at some later time within a new
+% output routine
+% for \LaTeX. They are not (yet) meant for general use and are
+% therefore made internal, even though we already use them in
+% \pkg{multicol}.
+% Internal means that \verb|@@| automatically gets
+% replaced in the code (and in the documentation) so we have to give
+% it a suitable value.
+% \begin{macrocode}
+%<@@=mark>
+% \end{macrocode}
+%
+% \begin{function}{\@@_update_singlecol_structures:}
+% \begin{syntax}
+% \cs{@@_update_singlecol_structures:}
+% \end{syntax}
+% \LaTeXe{} integration function in case we are doing single column
+% layouts. It assumes that the page content is already stored in
+% \cs{@outputbox} and processes the marks inside that box. It is
+% called as part of \cs{@opcol}.
+% \end{function}
+%
+%
+% \begin{function}{\@@_update_dblcol_structures:}
+% \begin{syntax}
+% \cs{@@_update_singlecol_structures:}
+% \end{syntax}
+% \LaTeXe{} integration function mark used when we are doing double
+% column documents. It assumes that the page content is already
+% stored in \cs{@outputbox} and processes the marks inside that
+% box. It then does different post-processing depending on the start
+% of the switch \cs{if at firstcolumn}. If we are in the second column
+% it also has to update page marks, otherwise it only updates column
+% marks. It too is called as part of \cs{@opcol}.
+% \end{function}
+%
%
% ^^A \end{documentation}
%
@@ -1019,9 +1029,9 @@
%
% 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
+% \cs{mark_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
+% \cs{mark_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}
@@ -1261,7 +1271,7 @@
% \end{macrocode}
% \end{macro}
%
-% \begin{macro}{\@@_update_structure_from_material:nn}
+% \begin{macro}{\mark_update_structure_from_material:nn}
%
% \changes{v1.0e}{2024/01/29}{Macro renamed}
%
@@ -1272,7 +1282,7 @@
% the assignments.
%
% \begin{macrocode}
-\cs_new_protected:Npn \@@_update_structure_from_material:nn #1#2 {
+\cs_new_protected:Npn \mark_update_structure_from_material:nn #1#2 {
\@@_extract_and_handle_marks:nn
% \end{macrocode}
%
@@ -1298,7 +1308,7 @@
% \texttt{previous-...}; this leaves the current structure
% untouched so we can update it class by class (as is necessary).
% \begin{macrocode}
- \@@_copy_structure:nn { previous-#1 } {#1}
+ \mark_copy_structure: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
@@ -1370,7 +1380,7 @@
%
%
%
-% \begin{macro}{\@@_get_marks_for_reinsertion:nNN}
+% \begin{macro}{\mark_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,
@@ -1383,7 +1393,7 @@
% really clear that this is never needed.}
%
% \begin{macrocode}
-\cs_new_protected:Npn \@@_get_marks_for_reinsertion:nNN #1#2#3 {
+\cs_new_protected:Npn \mark_get_marks_for_reinsertion:nNN #1#2#3 {
% \end{macrocode}
% First we clear the temporary token lists as we haven't seen any marks yet.
% \begin{macrocode}
@@ -1512,13 +1522,13 @@
% \end{macro}
%
%
-% \begin{macro}{\@@_copy_structure:nn}
+% \begin{macro}{\mark_copy_structure:nn}
% This function copies the structure for one region to another,
% e.g., from \texttt{page} to \texttt{previous-page} above,
% or later from \texttt{column} to \texttt{first-column}, etc.
% \changes{v1.1a}{2024/11/09}{Macro renamed}
% \begin{macrocode}
-\cs_new_protected:Npn \@@_copy_structure:nn #1#2 {
+\cs_new_protected:Npn \mark_copy_structure:nn #1#2 {
% \end{macrocode}
% This requires a simple loop through all mark classes copying the
% token list from one name to the next.
@@ -1537,12 +1547,12 @@
% \end{macro}
%
%
-% \begin{macro}{\@@_clear_structure:n}
+% \begin{macro}{\mark_clear_structure:n}
% This function sets the structure of one region back to an initial
% state, i.e., all classes return an empty value if queried.
% \changes{v1.1a}{2024/11/09}{}
% \begin{macrocode}
-\cs_new_protected:Npn \@@_clear_structure:n #1 {
+\cs_new_protected:Npn \mark_clear_structure:n #1 {
% \end{macrocode}
% This requires a simple loop through all mark classes.
% \begin{macrocode}
@@ -1561,11 +1571,11 @@
%
%
%
-% \begin{macro}{\@@_set_structure_to_err:n,\@@_error:n}
+% \begin{macro}{\mark_set_structure_to_err:n,\@@_error:n}
% A slight variation is to install a fixed error message as the
% value.
% \begin{macrocode}
-\cs_new_protected:Npn \@@_set_structure_to_err:n #1 {
+\cs_new_protected:Npn \mark_set_structure_to_err:n #1 {
\seq_map_inline:Nn \g_@@_classes_seq
{
\tl_gset:ce { g_@@_ #1 _top_ ##1 _tl } { \@@_value:nn{?}{\@@_error:nn {#1}{?} }}
@@ -1722,7 +1732,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 and only after \cs{@@_update_structure_from_material:nn} has acted,
+% in output routines and only after \cs{mark_update_structure_from_material:nn} has acted,
% otherwise their value will be wrong.
%
% \begin{macrocode}
@@ -2076,20 +2086,20 @@
% \begin{macrocode}
\box_if_vertical:NTF \@outputbox
{
- \@@_update_structure_from_material:nn {page}
+ \mark_update_structure_from_material:nn {page}
{ \vbox_unpack:N \@outputbox }
}
{
- \@@_update_structure_from_material:nn {page}
+ \mark_update_structure_from_material:nn {page}
{ \hbox_unpack:N \@outputbox }
}
% \end{macrocode}
% Then we provide the necessary updates for the aliases.
% \begin{macrocode}
- \@@_copy_structure:nn {previous-column}{previous-page}
- \@@_copy_structure:nn {column}{page}
- \@@_copy_structure:nn {first-column}{page}
- \@@_copy_structure:nn {last-column}{page}
+ \mark_copy_structure:nn {previous-column}{previous-page}
+ \mark_copy_structure:nn {column}{page}
+ \mark_copy_structure:nn {first-column}{page}
+ \mark_copy_structure:nn {last-column}{page}
%<*trace>
% move this into status itself?
\@@_debug:n
@@ -2121,11 +2131,11 @@
% \begin{macrocode}
\box_if_vertical:NTF \@outputbox
{
- \@@_update_structure_from_material:nn {column}
+ \mark_update_structure_from_material:nn {column}
{ \vbox_unpack:N \@outputbox }
}
{
- \@@_update_structure_from_material:nn {column}
+ \mark_update_structure_from_material:nn {column}
{ \hbox_unpack:N \@outputbox }
}
% \end{macrocode}
@@ -2140,8 +2150,8 @@
% \texttt{first-column} and there is no \texttt{last-column} yet,
% so we make those an error.
% \begin{macrocode}
- \@@_copy_structure:nn {first-column}{column}
- \@@_set_structure_to_err:n {last-column}
+ \mark_copy_structure:nn {first-column}{column}
+ \mark_set_structure_to_err:n {last-column}
}
{
% \end{macrocode}
@@ -2151,11 +2161,11 @@
% (because is was set to \texttt{column} last time which is now the
% \texttt{previous-column}), thus there is no need to make an update.
% \begin{macrocode}
-% \@@_copy_structure:nn {first-column}{previous-column}
+% \mark_copy_structure:nn {first-column}{previous-column}
% \end{macrocode}
% However, we now have a proper \texttt{last-column} so we assign that.
% \begin{macrocode}
- \@@_copy_structure:nn {last-column}{column}
+ \mark_copy_structure:nn {last-column}{column}
% \end{macrocode}
% What now remains doing is to update the \texttt{page} and
% \texttt{previous-page} regions. For this we have to copy the
diff --git a/required/tools/multicol.dtx b/required/tools/multicol.dtx
index 6b1d74996..70de9bb03 100644
--- a/required/tools/multicol.dtx
+++ b/required/tools/multicol.dtx
@@ -4381,7 +4381,7 @@
% least empty them, not sure what is better).
% \begin{macrocode}
\int_step_inline:nnn {\col at number + 1} { \g_@@_curr_col_int }
- { \__mark_set_structure_to_err:n { mcol - ##1 } }
+ { \mark_set_structure_to_err:n { mcol - ##1 } }
% \end{macrocode}
%
% There is no need to do anything to \texttt{mcol-1} up to
@@ -4399,7 +4399,7 @@
% \begin{macrocode}
\process at cols\mult at firstbox
{
- \__mark_update_structure_from_material:nn
+ \mark_update_structure_from_material:nn
%fmi {mcol}
{column}
{\unvcopy\count@}
@@ -4408,7 +4408,7 @@
% \texttt{mcol-\meta{\cs{\detokenize{g_@@_curr_col_int}}}} and then increment
% the counter.
% \begin{macrocode}
- \__mark_copy_structure:nn
+ \mark_copy_structure:nn
{mcol - \int_use:N\g_@@_curr_col_int }
%fmi {mcol}
{column}
@@ -4418,11 +4418,11 @@
% The above loop takes care of all columns, except for the last one
% (which is stored in \cs{mult at rightbox}. So we have to do that separately.
% \begin{macrocode}
- \__mark_update_structure_from_material:nn
+ \mark_update_structure_from_material:nn
%fmi {mcol}
{column}
{\unvcopy\mult at rightbox}
- \__mark_copy_structure:nn
+ \mark_copy_structure:nn
{ mcol - \int_use:N\g_@@_curr_col_int }
%fmi {mcol}
{column}
@@ -4430,9 +4430,9 @@
% Two more aliases to take care of: \texttt{first-column} and
% \texttt{last-column} and we are done:
% \begin{macrocode}
- \__mark_copy_structure:nn{first-column}{mcol-1}
-%fmi \__mark_copy_structure:nn{last-column} {mcol}
- \__mark_copy_structure:nn{last-column} {column}
+ \mark_copy_structure:nn{first-column}{mcol-1}
+%fmi \mark_copy_structure:nn{last-column} {mcol}
+ \mark_copy_structure:nn{last-column} {column}
}
% \end{macrocode}
% \end{macro}
@@ -4454,7 +4454,7 @@
% column they appear, we simply string together all columns in a big
% box and update the structure from that.
% \begin{macrocode}
- \__mark_update_structure_from_material:nn
+ \mark_update_structure_from_material:nn
{page}
{
% \end{macrocode}
@@ -4489,7 +4489,7 @@
% so we can later execute such token lists directly (and if there
% were no marks they will be empty).
% \begin{macrocode}
- \__mark_get_marks_for_reinsertion:nNN
+ \mark_get_marks_for_reinsertion:nNN
{
\process at cols \mult at firstbox { \unvcopy\count@ }
\unvcopy\mult at rightbox
@@ -4540,10 +4540,10 @@
% routine by copying the \texttt{page} region.
% \begin{macrocode}
\legacy_if:nT { @boxedmulticols }
- { \__mark_copy_structure:nn{saved-column}{column} }
+ { \mark_copy_structure:nn{saved-column}{column} }
\@@_debug_marks:n
{ \typeout{Marks:~ empty~ mcol~ regions~ (multicol)} }
- \__mark_clear_structure:n {column}
+ \mark_clear_structure:n {column}
}
% \end{macrocode}
% \end{macro}
@@ -4571,7 +4571,7 @@
% boxed \mc{} environment.
% \begin{macrocode}
\legacy_if:nT { @boxedmulticols }
- { \__mark_copy_structure:nn {column}{saved-column} }
+ { \mark_copy_structure:nn {column}{saved-column} }
}
% \end{macrocode}
More information about the latex3-commits
mailing list.