[latex3-commits] [latex3/latex2e] ltmarks-multicol: more docu (cf8bc9fff)
github at latex-project.org
github at latex-project.org
Sun Nov 10 15:05:26 CET 2024
Repository : https://github.com/latex3/latex2e
On branch : ltmarks-multicol
Link : https://github.com/latex3/latex2e/commit/cf8bc9fff56359588b5de81b50cb734a9dff6b04
>---------------------------------------------------------------
commit cf8bc9fff56359588b5de81b50cb734a9dff6b04
Author: Frank Mittelbach <frank.mittelbach at latex-project.org>
Date: Sun Nov 10 15:05:26 2024 +0100
more docu
>---------------------------------------------------------------
cf8bc9fff56359588b5de81b50cb734a9dff6b04
base/changes.txt | 10 +++++++
base/ltmarks.dtx | 69 +++++++++++++++++++++++++++------------------
required/tools/multicol.dtx | 4 +--
3 files changed, 53 insertions(+), 30 deletions(-)
diff --git a/base/changes.txt b/base/changes.txt
index 7490151f8..767571565 100644
--- a/base/changes.txt
+++ b/base/changes.txt
@@ -1,3 +1,13 @@
+2024-11-10 Frank Mittelbach <Frank.Mittelbach at latex-project.org>
+
+ * ltmarks.dtx (subsection{Placing and retrieving marks}):
+ Generate an error if \FirstMark etc, try to query for an unknown
+ region or class to avoid low-level errors later on.
+
+ Renamed \__mark_update_structure_alias:nn to \__mark_update_alias_structure:nn
+
+ Added \__mark_clear_structure:n
+
================================================================================
This file lists changes to the LaTeX2e files in reverse chronological order
of publication (therefore the dates might be out of sequence if there are
diff --git a/base/ltmarks.dtx b/base/ltmarks.dtx
index ea9c2bdea..a570dc625 100644
--- a/base/ltmarks.dtx
+++ b/base/ltmarks.dtx
@@ -213,7 +213,8 @@
% to the way \LaTeX{} cuts text material into pages.
% There is, however, one exception: if you produce multiple columns
% using the \pkg{multicol} package, it is possible to retrieve mark
-% values from the regions \texttt{mcol-1},
+% values from the regions \texttt{first-column},
+% \texttt{last-column}, \texttt{mcol-1},
% \texttt{mcol-2},\ldots\ directly after the environment has
% ended. This can, for example, be useful if a \env{multicols} has
% been be used inside a box.
@@ -334,36 +335,41 @@
% means you are able to access mark information for the current page
% as well as for the page before if you are inside the output
% routine, without the need to explicitly save that information
-% beforehand.
+% beforehand. The \texttt{page} region is the region that is most
+% often queried, which is why commands like \cs{FirstMark} use that
+% region is the default.
%
% In single column documents the \texttt{column} is the same as the
-% \texttt{page} region, but in two-column documents (not produced by
-% \env{multicols}), \texttt{column}
-% refers to the current column that just got finished and
-% \text{previous-column} to the one previously finished. Code for
-% running headers are (in standard \LaTeX{}) only evaluated when
-% both columns are assembled, which is another way of saying that in
-% that case \texttt{previous-column} refers to the left column and
-% \texttt{column} to the right column.
+% \texttt{page} region, but in two-column documents (if not produced
+% by \env{multicols}), \texttt{column} refers to the current column
+% that just got finished and \text{previous-column} to the one
+% previously finished. Code for running headers are (in standard
+% \LaTeX{}) only evaluated when both columns are assembled, which is
+% another way of saying that in that case \texttt{previous-column}
+% refers to the left column and \texttt{column} to the right column.
% However, to make this a bit nicer to access, there are also alias
% regions named \texttt{first-column} and
-% \texttt{last-column}\footnote{This is called \enquote{last} not \enquote{second}
-% in anticipation of extending the mechanism to multiple columns,
-% where first and last would still make sense.} to
+% \texttt{last-column}\footnote{This is called \enquote{last} not
+% \enquote{second} in anticipation of extending the mechanism to
+% multiple columns, where first and last would still make sense.} to
% access these regions.\footnote{There aren't any
-% \texttt{previous-...-column} regions to access the columns from
-% the previous page.}
-%
-% Note that you can only look backwards at already processed regions,
-% e.g., in a \texttt{twoside} document finishing a recto (odd,
-% right-hand) page you can access the data from the facing verso
-% (left-hand) page, but if you are finishing a left-hand page you
-% can't integrate data from the upcoming right-hand page. If such a
-% scenario needs to be realized then it is necessary to save the
-% left-hand page temporarily instead of finalizing it, process
+% \texttt{previous-...-column} regions to access the corresponding
+% columns from the previous page.}
+%
+% Note that you can only look backwards at already processed
+% regions, e.g., in a \texttt{twoside} document finishing a recto
+% (odd, right-hand) page you can access the data from the facing
+% verso (left-hand) page, but if you are finishing a left-hand page
+% you can't integrate data from the upcoming right-hand page. If
+% such a scenario needs to be realized then it is necessary to save
+% the left-hand page temporarily instead of finalizing it, process
% material for the right-hand page and once both are ready, attach
% running headers and footers and shipout out both in one
-% go.\footnote{As of now that scenario is not (yet) officially supported.}
+% go.\footnote{As of now that scenario is not (yet) officially
+% supported but it would be possible to construct it using the
+% shipout hooks to store the verso page and then on the next shipout
+% use the hook to shipout both with running headers and footers
+% attached.}
%
% The situation starts getting rather complex if you allow for
% multiple columns the way they are supported with the
@@ -778,9 +784,9 @@
% when we have just processed the first column in a two-column document.
% \end{function}
%
-% \begin{function}{\@@_update_structure_to_empty:n}
+% \begin{function}{\@@_clear_structure:n}
% \begin{syntax}
-% \cs{@@_update_structure_to_empty:n} \Arg{region}
+% \cs{@@_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{mcol} when a multicol
@@ -923,6 +929,10 @@
\@@_init_region:nn {first-column}{#1}
\@@_init_region:nn {last-column}{#1}
% \end{macrocode}
+% To support multiple columns produced by the \pkg{multicol}
+% package, we preallocate twenty alias regions (that is what
+% \pkg{multicol} supports as a maximum). They are filled by copying
+% the current \texttt{column} into the appropiate \texttt{mcol-...}.
% \begin{macrocode}
%fmi \@@_init_region:nn {mcol}{#1}
%fmi \@@_init_region:nn {previous-mcol}{#1}
@@ -1496,6 +1506,7 @@
% This function copies the structure for one region to another
% (name), 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 \@@_update_alias_structure:nn #1#2 {
% \end{macrocode}
@@ -1516,11 +1527,12 @@
% \end{macro}
%
%
-% \begin{macro}{\@@_update_structure_to_empty:n}
+% \begin{macro}{\@@_clear_structure:n}
% This function set 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 \@@_update_structure_to_empty:n #1 {
+\cs_new_protected:Npn \@@_clear_structure:n #1 {
% \end{macrocode}
% This requires a simple loop through all mark classes.
% \begin{macrocode}
@@ -1717,6 +1729,7 @@
% you only see something like
% \verb=\__mark_error:n{page}=.
% Not that great but better than low-level errors, I guess.
+% \changes{v1.1a}{2024/11/09}{}
% \begin{macrocode}
\cs_new:Npn \@@_use_check:nn #1#2 {
\tl_if_eq:cNTF {#1} \relax
diff --git a/required/tools/multicol.dtx b/required/tools/multicol.dtx
index 7bfe2254b..7e0b984e5 100644
--- a/required/tools/multicol.dtx
+++ b/required/tools/multicol.dtx
@@ -4446,9 +4446,9 @@
% \begin{macrocode}
\def \mc at prepar@mark at collection {
%fmi \@@_debug:n { \typeout{--->>>~ multicol~ empty~ mcol} }
-%fmi \@@_update_structure_to_empty:n {mcol}
+%fmi \@@_clear_structure:n {mcol}
\@@_debug:n { \typeout{--->>>~ multicol~ empty~ column~ region} }
- \@@_update_structure_to_empty:n {column}
+ \@@_clear_structure:n {column}
}
% \end{macrocode}
% \end{macro}
More information about the latex3-commits
mailing list.