updatemarks (19feb24)

git-svn-id: svn://tug.org/texlive/trunk@69986 c570f23f-e606-0410-a88d-b1316a301751

3 files changed, 82 insertions, 16 deletions

diff --git a/Master/texmf-dist/doc/latex/updatemarks/README.md b/Master/texmf-dist/doc/latex/updatemarks/README.md
index eb3a99d23cb..57f5f3cb566 100644
--- a/Master/texmf-dist/doc/latex/updatemarks/README.md
+++ b/Master/texmf-dist/doc/latex/updatemarks/README.md
@@ -8,6 +8,6 @@ use `\UpdateMarks` to reinsert marks. Read the documentation for more details.
 
 # Copyright and License
 
-Copyright 2023 Wenjian Chern
+Copyright 2023, 2024 Wenjian Chern
 
 LICENSE: [LPPL 1.3c](http://www.latex-project.org/lppl.txt)
diff --git a/Master/texmf-dist/doc/latex/updatemarks/updatemarks.pdf b/Master/texmf-dist/doc/latex/updatemarks/updatemarks.pdf
index f6e45818968..7c2e6e949bb 100644
--- a/Master/texmf-dist/doc/latex/updatemarks/updatemarks.pdf
+++ b/Master/texmf-dist/doc/latex/updatemarks/updatemarks.pdf
diff --git a/Master/texmf-dist/doc/latex/updatemarks/updatemarks.tex b/Master/texmf-dist/doc/latex/updatemarks/updatemarks.tex
index 2de3b6bded3..a462711ab9a 100644
--- a/Master/texmf-dist/doc/latex/updatemarks/updatemarks.tex
+++ b/Master/texmf-dist/doc/latex/updatemarks/updatemarks.tex
@@ -4,7 +4,7 @@
 
 \title{Update marks in box\thanks{Issues: \url{https://github.com/Sophanatprime/updatemarks/issues}}}
 \author{WenJian Chern\thanks{Email: longaster@163.com}}
-\date{\today\qquad v0.2b}
+\date{\today\qquad v0.2e}
 
 \begin{document}
 
@@ -59,9 +59,9 @@ But, if you put \env{minipage} in \env{tcolorbox} or the other way round,
 
 The point is, updating marks is done inner to outer and level by level, 
 if any level is not updated, you will lost all marks in inner boxes.
-Furthermore, whether marks are updated or not {\TeX} is only influenced by box level
+Furthermore, whether marks are updated or not is only influenced by box level
 instead of group level, so if you try to limit marks in a certain position, you should
-use a box.
+use a box instead of \tn{begingroup} and \tn{endgroup}.
 
 The extracting and updating would not remove these marks, they still be there, you 
 can find them by your own method as well.
@@ -82,7 +82,8 @@ including \env{varwidth} of \pkg{varwidth} package, etc.
 
 If \env{multicols} or \env{adjmulticols} or their starred versions are put in a box
 --- so called \emph{boxed multicols}, you are able to eanble automatically extracting 
-and updating marks into the box (not outer of the box, because it only ).
+and updating marks into the box (not outer of the box, because they are only updated
+one level).
 If you need to update marks in this box, you have to do it manually.
 Of cause, if the box is \env{minipage} or \env{tcolorbox} or another \env{multicols}
 or any other supported environments or commands, then no more things to do.
@@ -96,7 +97,7 @@ are not correct. Multiple contiguous forced break or \tn{clearpage} may cause th
 wrong marks.
 
 If your {\LaTeX} version is 2022-06-01 or newer,
-you can get more accurate mark values by using \cs{TopMark}, \cs{FirstMark} 
+you can get more correct mark values by using \cs{TopMark}, \cs{FirstMark} 
 and \cs{LastMark} in head and foot, but only the 
 \texttt{previous-page} region and \texttt{page} region are supported for now.
 Still, Multiple contiguous forced break or \tn{clearpage} may cause the wrong marks.
@@ -122,8 +123,6 @@ automatical updating list. If you are not using these two commands, then nothing
 to be done.
 
 
-\enlargethispage{20pt}
-
 \begin{function}{\AddToUpdateMarksList,\SetUpdateMarksList,\RemoveFromUpdateMarksList}
   \begin{syntax}
     \verb|\AddToUpdateMarksList|      \marg{number list}
@@ -139,6 +138,7 @@ Specially, for those mark classes declared by \cs{NewMarkClass}, you are able to
 \begin{verbatim}
   \RemoveFromUpdateMarksList { [2e-right], 4, \MarkClass{my-class} }
 \end{verbatim}
+You can also use number ranges in \meta{number list}, such as \verb|2 -> 5|.
 \end{function}
 
 
@@ -205,8 +205,22 @@ or if not in a box then the main vertical list.
 
 If \meta{number list} is presented, the mark classes are these numbers, otherwise
 they are the automatical updating list.
+
+\texttt{insertmark} hook would not be used as it's already been used.
 \end{function}
 
+\begin{function}[added=2024-02-19]{\ExtractMarksTo}
+  \begin{syntax}
+    \verb|\ExtractMarks| \marg{box number} \marg{cmd}
+    \verb|\ExtractMarks| \oarg{number list} \marg{box number} \marg{cmd}
+    \verb|\ExtractMarks| * \marg{text} \marg{cmd}
+    \verb|\ExtractMarks| * \oarg{number list} \marg{text} \marg{cmd}
+  \end{syntax}
+It collect all marks to \tn[no-index]{cmd}, you can use \tn[no-index] to reinsert
+these marks.
+
+\texttt{insertmark} hook would not be used as it's already been used.
+\end{function}
 
 \section{Disable patches or write your own patches}
 
@@ -230,15 +244,21 @@ you are able set them in preamble before or after \pkg{updatemarks} is loaded.
 
 This section describes the interfaces of \LaTeX3.
 
+\begin{function}[added=2024-02-19]{\updatemarks_parse_classes:Nn}
+  \begin{syntax}
+    \verb|\updatemarks_parse_classes:Nn| \meta{seq var} \marg{number list}
+  \end{syntax}
+Parse number list and save it to \meta{seq var}.
+\end{function}
+
 \begin{function}{\updatemarks_extract:nN,\updatemarks_extract_split:N}
   \begin{syntax}
-    \verb|\updatemarks_extract:nN| \marg{box material} \meta{seq var}
+    \verb|\updatemarks_extract:nN| \marg{material} \meta{seq var}
     \verb|\updatemarks_extract_split:N| \meta{seq var}
   \end{syntax}
-These two functions have the same functions of 
-\cs{ExtractMarks} and \cs{ExtractSplitMarks}.
+Programming interface of \cs{ExtractMarks} and \cs{ExtractSplitMarks}, respectively.
 
-\meta{box material} is content to build a box.
+\meta{material} is content to build a box.
 Such as unpacked box using \cs{hbox_unpack:N} or \cs{vbox_unpack:N} or text.
 
 \meta{seq var} is the number sequence of mark classes which are need to be extracted.
@@ -246,6 +266,26 @@ Such as unpacked box using \cs{hbox_unpack:N} or \cs{vbox_unpack:N} or text.
 They only save the marks whose positions are first or last.
 \end{function}
 
+\begin{function}[added=2024-02-19]{\updatemarks_extract:nNN}
+  \begin{syntax}
+    \verb|\updatemarks_extract:nNN| \marg{material} \meta{seq var} \meta{tl var}
+  \end{syntax}
+Programming interface of \cs{ExtractMarksTo}.
+
+\texttt{insertmark} hook would not be used as it's already been used.
+\end{function}
+
+\begin{function}[added=2024-02-19]{\updatemarks_extract_act:nNn}
+  \begin{syntax}
+    \verb|\updatemarks_extract_act:nNn| \marg{material} \meta{seq var} \marg{code}
+  \end{syntax}
+Run \meta{code} for every mark classes in \meta{seq var}, the code can use one 
+parameter, which is the current mark class, and two \texttt{tl} variable
+\cs{l_updatemarks_first_tl} and \cs{l_updatemarks_last_tl}, which save
+the first and last marks at specified mark class, respectively. If these two \texttt{tl}
+is not exist, then no marks at the mark class are inserted.
+\end{function}
+
 \begin{function}{\updatemarks_update:N}
   \begin{syntax}
     \verb|\updatemarks_update:N| \meta{seq var}
@@ -256,6 +296,8 @@ This function has the same function of \cs{UpdateMarks}.
 reinserted into the current box or the main vertical list.
 
 It only reinserts marks whose positions are first or last.
+
+\texttt{insertmark} hook would not be used as it's already been used.
 \end{function}
 
 \begin{function}{\updatemarks_save:Nnn}
@@ -264,18 +306,28 @@ It only reinserts marks whose positions are first or last.
   \end{syntax}
 Saving marks at \meta{position} of specified mark classes \meta{seq var},
 whose values are expanding \meta{value code} \emph{once}.
+
+If \cs{l_updatemarks_nonempty_bool} is set to \texttt{true}, then the expanded value
+will not be saved if it is total empty.
+
 The \meta{value code} receives each item in the \meta{seq var} 
-as a trailing brace group.
+as a trailing brace group, than expand the whole part of
+\meta{value code} and the trailing group \emph{once}.
 \end{function}
 
-\begin{function}{\updatemarks_save_x:Nnn}
+\begin{function}{\updatemarks_save_e:Nnn}
   \begin{syntax}
-    \verb|\updatemarks_save_x:Nnn| \meta{seq var} \marg{position} \marg{value code}
+    \verb|\updatemarks_save_e:Nnn| \meta{seq var} \marg{position} \marg{value code}
   \end{syntax}
 Saving marks at \meta{position} of specified mark classes \meta{seq var},
 whose values are fully expanding \meta{value code}.
+
+If \cs{l_updatemarks_nonempty_bool} is set to \texttt{true}, then the expanded value
+will not be saved if it is total empty.
+
 The \meta{value code} receives each item in the \meta{seq var} 
-as a trailing brace group.
+as a trailing brace group, then \emph{fully expand} the whole part of 
+\meta{value code} and the trailing group.
 \end{function}
 
 \begin{function}{\updatemarks_alias:Nnn}
@@ -284,6 +336,9 @@ as a trailing brace group.
   \end{syntax}
 Setting marks at \meta{alias position} are equal to \meta{source position} 
 of specified mark classes \meta{seq var}.
+
+If \cs{l_updatemarks_nonempty_bool} is set to \texttt{true}, then the expanded value
+will not be saved if it is total empty.
 \end{function}
 
 \begin{function}{\updatemarks_remove:Nn}
@@ -318,5 +373,16 @@ Readonly number sequence which holds the mark classes allocated by
 \cs{NewMarkClass}. If \cs{NewMarkClass} is undefined, then it's empty.
 \end{function}
 
+\begin{function}{\l_updatemarks_nonempty_bool}
+A local \texttt{bool} variable which is used to control if is going to save 
+a total empty value.
+\end{function}
+
+\begin{function}{\l_updatemarks_first_tl,\l_updatemarks_last_tl}
+A local \texttt{tl} variable which are use to save the first and last marks.
+\end{function}
+
+
+\PrintIndex
 
 \end{document}
\ No newline at end of file