[latex3-commits] [latex3/latex2e] ltmarks-multicol: updates after review by Chris (c267caa26)
github at latex-project.org
github at latex-project.org
Sun Nov 17 12:42:50 CET 2024
Repository : https://github.com/latex3/latex2e
On branch : ltmarks-multicol
Link : https://github.com/latex3/latex2e/commit/c267caa26b4c14714f4925f1093ca204a750b91a
>---------------------------------------------------------------
commit c267caa26b4c14714f4925f1093ca204a750b91a
Author: Frank Mittelbach <frank.mittelbach at latex-project.org>
Date: Sun Nov 17 12:42:50 2024 +0100
updates after review by Chris
>---------------------------------------------------------------
c267caa26b4c14714f4925f1093ca204a750b91a
base/ltmarks.dtx | 121 ++++++++++++++++++++++++++++---------------------------
1 file changed, 61 insertions(+), 60 deletions(-)
diff --git a/base/ltmarks.dtx b/base/ltmarks.dtx
index c4fbbb6ee..cfada0429 100644
--- a/base/ltmarks.dtx
+++ b/base/ltmarks.dtx
@@ -233,7 +233,7 @@
% \texttt{mcol-2} (second column in a \env{multicols}),
% up to
% \texttt{mcol-20} (twentieth column in a \env{multicols}).
-% See section~\ref{sec:regions} for a discussion how these regions
+% See section~\ref{sec:regions} for discussion of how these regions
% behave and how one can make use of them.
%
%
@@ -331,10 +331,10 @@
%
% If a page has just been finished then the region \texttt{page}
% refers to the current page and \texttt{previous-page}, as the name
-% indicates, to the page that has been finished previously. This
+% indicates, refers to the page before the current page. This
% 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
+% as well as for the page before (as long as you are inside the output
+% routine) without the need to explicitly save that information
% beforehand. The \texttt{page} region is the region that is most
% often queried, which is why commands like \cs{FirstMark} use that
% region by default.
@@ -344,16 +344,17 @@
% 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
+% \LaTeX{}) only evaluated only after both columns have been 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
-% access these regions.\footnote{There aren't any
-% \texttt{previous-...-column} regions to access the corresponding
+% However, to make these somewhat easier to use, there are also aliased names
+% for these two regions: \texttt{first-column} and
+% \texttt{last-column}.\footnote{The region is called \enquote{last-column} not
+% \enquote{second-column} in anticipation of extending the mechanism to
+% multiple columns, where first and last would still make sense.
+% There aren't any
+% \texttt{previous-first-column} and \texttt{previous-last-column}
+% regions to access the corresponding
% columns from the previous page.}
%
% Note that you can only look backwards at already processed
@@ -366,31 +367,31 @@
% 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 but it would be possible to construct it using the
+% supported but it would be possible to achieve this 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
+% multiple columns the way they are supported by the
% \pkg{multicol} package. In that case you might have a varying
% number of \enquote{columns} on a single page to be shipped
% out. And even if not, then a \env{multicols} might start or end in
-% the middle of the page and in either case the regions \texttt{column} and
+% the middle of the page; in either case, the regions \texttt{column} and
% \texttt{previous-column} become rather meaningless and you should
% therefore not use them.\footnote{They return something, because
% they represent the last two columns of the \env{multicols} when
% you are inside the output routine, but that is obviously of little
-% use for a real use case.}
+% use.}
% Instead, the algorithm offers \texttt{mcol-1}, \texttt{mcol-2},
-% \texttt{mcol-3}, etc., representing the columns in the
+% \texttt{mcol-3}, etc., to represent the columns in the
% \env{multicols} on the current page to be shipped out. If there is
-% more than one \env{multicols} on the current page then you see the
-% columns of the last one inside the output routine.
+% more than one \env{multicols} on the current page then in the output routine
+% only the columns of the last one will be accessible.
%
-% This covers a number of layouts and use cases out of the box, but
-% obviously not all. However, more can be supported by storing away
-% mark information during the processing. So here is the full
+% These provisions covers a number of layouts and use cases out of the box, but
+% obviously not all. However, more cases can be supported by storing away
+% mark information during the processing. Here is the full
% algorithm:
% \begin{itemize}
% \item
@@ -403,7 +404,7 @@
% \item
% When the \env{multicols} starts, the \texttt{column} region is
-% cleared, i.e., from that point on it looks as it there have not
+% cleared, i.e., from that point on it looks as if there have not
% been any marks so far. This will make sure that the top mark in
% the first column is always empty.
%
@@ -422,7 +423,7 @@
% column is placed into the \texttt{column} region. Then we alias
% \texttt{column} to \texttt{mcol-1}.
%
-% \item This is repeated for all columns of the \env{multicols}
+% \item These steps are repeated for all columns of the \env{multicols}
% environment.
%
% \item Finally, the first and the last column of that page is also
@@ -431,14 +432,14 @@
% \end{itemize}
%
% \item
-% All marks inside any of the columns are also available in the
+% All those marks inside any of the columns are also available in the
% \texttt{page} region. Thus, if you are interested in the top,
% first, or last mark of a specific class on the whole page you
-% simply have to query for it in the \texttt{page} region.
+% simply need to query for it in the \texttt{page} region.
%
% \item
% If the \env{multicols} continues across several pages then
-% this algorithm is repeated, except that the \texttt{column}
+% this algorithm above is repeated for each page, except that the \texttt{column}
% region is not cleared again. This means that the top mark of
% the first column of the next page will be the last mark of the
% last column from the previous page.
@@ -456,7 +457,7 @@
%
% \item
% Then the balanced set of columns is returned back to the page
-% (since there is space for further material). In addition all
+% (since there may be space for further material). In addition, all
% marks inside that material are reinserted so that they become
% available in the \texttt{page} region.
%
@@ -798,7 +799,7 @@
% empty. This is currently used for \texttt{column} when a multicol
% environment starts because it wouldn't make sense if the top mark
% in the first column would return the last mark from a previous
-% multicol (which may have been much earlier with intermediate
+% multicol (which may have been much earlier, with intermediate
% material).
% \end{function}
%
@@ -815,7 +816,7 @@
% the output routine as well.
%
% It collects all the top-level marks from inside the \meta{source}
-% and adds suitable \cs{mark_insert:nn} in the two token
+% and then it 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, going to be used\footnote{Probably not before 2025, though.}
@@ -936,7 +937,7 @@
\@@_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
+% package, we preallocate twenty alias regions (since this is the number of columns what
% \pkg{multicol} supports as a maximum). They are filled by copying
% the current \texttt{column} into the appropriate \texttt{mcol-...}.
% \begin{macrocode}
@@ -969,8 +970,8 @@
%
% \begin{macro}{\@@_init_region:nn,\c_@@_empty_tl}
%
-% Per class (\texttt{\#2} we need three token lists for each
-% region: one for top, first, and last. The default value to be
+% For each class (\texttt{\#2}) and region (\texttt{\#1}), we need
+% three token lists: one for top, first, and last. The default value to be
% returned is \enquote{empty}.
% \begin{macrocode}
\cs_new_protected:Npn \@@_init_region:nn #1 #2 {
@@ -983,10 +984,12 @@
}
% \end{macrocode}
%
-% All marks will have an identification in form of a number that is
-% incremented each time a mark insertion happens and therefore the
-% initial empty values should have that too, so that data extraction
-% is going to be uniform.
+% All marks will have an identification in the form of a
+% number\footnote{There are a few cases where special
+% identification strings are used, e.g., \texttt{2.09-compat}.} that is
+% incremented each time a mark insertion happens; therefore the
+% initial empty values should also have such a number, so that data extraction
+% will be uniform.
% \changes{v1.0g}{2024/05/31}{Initialize all marks with an id, use
% \texttt{0} when a new class is made (gh/1359)}
% \begin{macrocode}
@@ -1293,7 +1296,7 @@
%
% 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).
+% untouched so we can update it class by class (as is necessary).
% \begin{macrocode}
\@@_copy_structure:nn { previous-#1 } {#1}
% \end{macrocode}
@@ -1392,8 +1395,8 @@
% \begin{macrocode}
\@@_extract_and_handle_marks:nn
% \end{macrocode}
-% The first argument holds the code for filling the token lists and
-% the second is the material we extract from.
+% The first argument holds the code used for filling the token lists and
+% the second holds the material from which all marks should be extracted.
% \begin{macrocode}
\@@_get_from_splitmarks:
{ #1 }
@@ -1485,7 +1488,7 @@
{
% \end{macrocode}
% We better drop the id from the returned value otherwise they
-% accumulate in the marks when reinserted.
+% will accumulate in the marks when reinserted.
% \begin{macrocode}
\@@_drop_id:o {
\tex_splitfirstmarks:D
@@ -1510,8 +1513,8 @@
%
%
% \begin{macro}{\@@_copy_structure:nn}
-% This function copies the structure for one region to another
-% (name), e.g., from \texttt{page} to \texttt{previous-page} above,
+% 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}
@@ -1535,7 +1538,7 @@
%
%
% \begin{macro}{\@@_clear_structure:n}
-% This function set the structure of one region back to an initial
+% 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}
@@ -1576,8 +1579,6 @@
% perhaps we end up with another reason to use this error command
% elsewhere, so for now we keep the argument.
%
-% This is not protected so that it expands, for example in a
-% \cs{typeout} to the next level.
% \begin{macrocode}
\cs_new_protected:Npn \@@_error:nn #1#2 {
\msg_error:nnnn { mark } { invalid-use } {#1} {#2}
@@ -1730,16 +1731,16 @@
\cs_new:Npn \mark_use_top:nn #1#2 { \@@_use_check:nnn { g_@@_#1_top_#2_tl } {#1} {#2} }
% \end{macrocode}
%
-% If used with an unknown class or region they generate an error.
+% If used with an unknown class or region these commands will generate an error.
% If that happens in an expandable context then the error
% generation is delayed (e.g., if used in a \cs{section}) and
-% happens if the code is finally used in typesetting, e.g., in the
+% happens when the code is finally used in typesetting, e.g., in the
% TOC or a running header.
% If used in a \cs{typeout} you only see something like
% \verb=\__mark_error:n{page}=.
-% The latter is not that great but better than low-level errors, I
-% guess, and I don't want to use an expandable error because of its
-% size restrictions.
+% This is not too good, but probably better than low-level errors, I
+% guess, and I don't want to use an expandable error because of the
+% size restrictions in such error messages.
% \changes{v1.1a}{2024/11/09}{}
% \begin{macrocode}
\cs_new:Npn \@@_use_check:nnn #1#2#3 {
@@ -1753,7 +1754,7 @@
% nevertheless better to remove it when returning the mark, so that
% downstream manipulation of the data doesn't have to deal with it.
% \changes{v1.0g}{2024/05/31}{Remove the id when returning the mark value (gh/1359)}
-% This is what the \cs{use_none:nn} accomplishes.
+% This is what the \cs{exp_not:o} accomplishes.
% \begin{macrocode}
\cs_new:Npn \@@_drop_id:n #1 { \exp_not:o { #1 } }
\cs_generate_variant:Nn \@@_drop_id:n { o, v }
@@ -1824,8 +1825,8 @@
}
% \end{macrocode}
%
-% Next error can also happen if the mark class is unknown, so this
-% should probably be separated into two different errors.
+% The next error can also happen if the mark class is unknown, so this
+% should perhaps be separated into two different errors.
% \begin{macrocode}
\msg_new:nnnn { mark } { invalid-use }
{ Mark~region~'#1'~not~usable~or~class~'#2'~unknown }
@@ -1904,10 +1905,10 @@
% (\verb=#2=).
%
% The first argument gives some \meta{info} to help
-% identifying where the command was called, the second is
+% in identifying where the command was called, the second is
% the class and the third holds the number of \texttt{mcol-...} we
-% should display (inside a \env{multicols} environment it will get \cs{col at number}
-% passed, in \LaTeX{}'s normal output routines it will be \texttt{0}.
+% should display: inside a \env{multicols} environment this will be \cs{col at number},
+% in \LaTeX{}'s normal output routines it will be \texttt{0}.
% \changes{v1.1a}{2024/11/09}{Add a third argument}
% \begin{macrocode}
%<*trace>
@@ -1920,7 +1921,7 @@
\@@_region_status:nnn {#2}{ column~ (first) } { first-column }
\@@_region_status:nnn {#2}{ column~ (last)~ } { last-column }
% \end{macrocode}
-% Display a subset of the \texttt{mcol-...} regions, by default 0
+% then finish by displaying a subset of the \texttt{mcol-...} regions: none (\texttt{0})
% in the standard \LaTeX{} output routine and \cs{col at number}
% within a \env{multicols} environment.
% \begin{macrocode}
@@ -1961,7 +1962,7 @@
% \begin{macro}{\@@_status:nn}
% Show a snapshot of all mark class values across all regions. The
% first argument is a string to identify the output, the second
-% argument is the number \texttt{mcol-...} regions to show. Outside
+% argument is the number of \texttt{mcol-...} regions to show. Outside
% of a \env{multicols} environment this is normally set to 0.
% \changes{v1.1a}{2024/11/09}{Add a second argument}
% \begin{macrocode}
@@ -2083,7 +2084,7 @@
{ \hbox_unpack:N \@outputbox }
}
% \end{macrocode}
-% The we provide the necessary updates for the aliases.
+% Then we provide the necessary updates for the aliases.
% \begin{macrocode}
\@@_copy_structure:nn {previous-column}{previous-page}
\@@_copy_structure:nn {column}{page}
More information about the latex3-commits
mailing list.