summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/updatemarks/doc/updatemarks.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/updatemarks/doc/updatemarks.tex')
-rw-r--r--macros/latex/contrib/updatemarks/doc/updatemarks.tex322
1 files changed, 322 insertions, 0 deletions
diff --git a/macros/latex/contrib/updatemarks/doc/updatemarks.tex b/macros/latex/contrib/updatemarks/doc/updatemarks.tex
new file mode 100644
index 0000000000..2de3b6bded
--- /dev/null
+++ b/macros/latex/contrib/updatemarks/doc/updatemarks.tex
@@ -0,0 +1,322 @@
+\documentclass{l3doc}
+\usepackage{updatemarks}
+\usepackage[a4paper,top=2cm,bottom=2.5cm,left=5cm,right=2cm]{geometry}
+
+\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}
+
+\begin{document}
+
+\maketitle
+
+\begin{abstract}
+There are some cases where one may put title in box and still want its
+\cs{markboth} working. This brings the \pkg{updatemarks} package.
+The \pkg{updatemarks} package provides interface to extract marks where are in a
+inner box and then can put the first and last marks back to outer.
+It can automatically update marks where are in \env{minipage},
+\textit{boxed multicols} and \env{tcolorbox} environments.
+\end{abstract}
+
+
+\tableofcontents
+
+
+\section{Usage of the package}
+
+You simply insert \verb|\usepackage{updatemarks}| or
+\verb|\usepackage|\oarg{options}\verb|{updatemarks}| in the preamble of your document.
+
+There are three package options \texttt{minipage},
+\texttt{multicol}(an optional \texttt s) and
+\texttt{tcolorbox}, which are used to enable the function of automatical updating marks
+in \env{minipage}, \env{multicols} and
+\env{tcolorbox} (both \env{tcolorbox} environment and \tn{tcbox} command), respectively.
+
+No automatical updatings are enable, by default.
+
+If your {\LaTeX} version is 2022-06-01 or newer, you can use
+\cs{SetKeys}\texttt{[updatemarks]}\marg{options} to enable or disable
+automatical updating locally.
+
+Such as,
+\begin{verbatim}
+ \SetKeys[updatemarks]{minipage=false, tcolorbox=true, multicol}
+\end{verbatim}
+so marks in \env{minipage} would not update,
+whereas \env{tcolorbox} and \env{multicols} do.
+
+The total empty mark will not be extracted and updated.
+But \verb|\markboth{}{}| and \verb|\InsertMark{}| do will be extracted and updated,
+because they are not total empty internally.
+
+However, the updating is not once for all.
+For example, if you are using \env{minipage} in \tn{makebox}, even if you enable
+the automatical updating, the marks still can not be found by \LaTeX.
+But, if you put \env{minipage} in \env{tcolorbox} or the other way round,
+\LaTeX\ still can get correct marks.
+
+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
+instead of group level, so if you try to limit marks in a certain position, you should
+use a box.
+
+The extracting and updating would not remove these marks, they still be there, you
+can find them by your own method as well.
+
+
+\section{\env{minipage}}
+
+You can enable automatically extracting and updating marks where are in \env{minipage}
+to its nearest outer box level,
+by using \texttt{minipage} package option or set \texttt{minipage} key to true.
+
+\pkg{updatemarks} patches the \tn{endminipage}, if you enable the function,
+marks in any other environments that use \env{minipage} will be updated,
+including \env{varwidth} of \pkg{varwidth} package, etc.
+
+
+\section{\pkg{multicol} and \pkg{adjmulticol}}
+
+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 ).
+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.
+
+All \env{multicols} and \env{adjmulticols} and their starred versions share the
+same option \texttt{multicol}(an optional \texttt s).
+
+For \emph{non boxed multicols}, i.e, not in any other box except
+the main vertical list, the \tn{topmark} (and \tn{topmarks}) at first and last page
+are not correct. Multiple contiguous forced break or \tn{clearpage} may cause the
+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}
+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.
+
+
+\section{\pkg{tcolorbox}}
+
+The \pkg{updatemarks} package can also update marks in \env{tcolorbox} environments
+(both breakable and unbreakable) and \tn{tcbox} commands.
+
+You are allowed to use \verb|updatemarks=true| or \verb|updatemarks| in \tn{tcbset}
+or as environment and command option to enable the function, and
+\verb|updatemarks=false| to disable.
+
+
+\section{Set automatical updating list}
+
+\pkg{updatemarks} can automatically detect mark classes allocated by \tn{newmarks}
+and \cs{NewMarkClass} in preamble. But if you allocate mark class after preamble
+(which I strongly recommend you do not),
+\pkg{updatemarks} also provides interfaces to enable you add these mark class to
+automatical updating list. If you are not using these two commands, then nothing need
+to be done.
+
+
+\enlargethispage{20pt}
+
+\begin{function}{\AddToUpdateMarksList,\SetUpdateMarksList,\RemoveFromUpdateMarksList}
+ \begin{syntax}
+ \verb|\AddToUpdateMarksList| \marg{number list}
+ \verb|\SetUpdateMarksList| \marg{number list}
+ \verb|\RemoveFromUpdateMarksList| \marg{number list}
+ \end{syntax}
+You can use these functions to globally add items to, set items, and remove items from
+the list of mark classes which need to be automatically updated.
+
+The \meta{number} is the first argument of \tn{newmarks}, or literally, a number.
+Specially, for those mark classes declared by \cs{NewMarkClass}, you are able to use
+\oarg{class} or \cs{MarkClass}\marg{class}. Such as
+\begin{verbatim}
+ \RemoveFromUpdateMarksList { [2e-right], 4, \MarkClass{my-class} }
+\end{verbatim}
+\end{function}
+
+
+\begin{function}{\AddAllocatedToUpdateMarksList}
+ \begin{syntax}
+ \verb|\AddAllocatedToUpdateMarksList|
+ \end{syntax}
+The function add all mark classes allocated by \tn{newmarks} and \cs{NewMarkClass}
+to automatical updating list.
+\end{function}
+
+
+\section{Generic interfaces of extracting and updating}
+
+If you need to extract and update marks manually, \cs{ExtractMarks},
+\cs{ExtractSplitMarks} and \cs{UpdateMarks} will help you.
+
+\begin{function}{\ExtractMarks}
+ \begin{syntax}
+ \verb|\ExtractMarks| \marg{box number}
+ \verb|\ExtractMarks| \oarg{number list} \marg{box number}
+ \verb|\ExtractMarks| * \marg{text}
+ \verb|\ExtractMarks| * \oarg{number list} \marg{text}
+ \end{syntax}
+Save first marks and last marks of specified mark classes
+which are directly presented in \meta{box number} or \meta{text}
+if these marks is not total empty.
+Marks in deeper boxes will not be detected, unless they are moved out.
+
+If \meta{number list} is presented, the mark classes are these numbers, otherwise
+they are the automatical updating list.
+
+The \meta{box number} is the first argument of \tn{newbox} or \tn{newsavebox}, etc.,
+and have saved contents by using \env{lrbox} or \tn{sbox} or similar.
+
+The \meta{text} is typeset material and \emph{will be executed}.
+
+If the \meta{box number} is a vbox and contains forced page break, then all marks after
+the first forced page break will not be detected.
+\end{function}
+
+\begin{function}{\ExtractSplitMarks}
+ \begin{syntax}
+ \verb|\ExtractSplitMarks|
+ \verb|\ExtractSplitMarks| \oarg{number list}
+ \end{syntax}
+This command is used after a \tn{vsplit}, and save
+first marks and last marks of specified mark classes which are directly
+presented in being split part if these marks is not total empty.
+Marks in deeper boxes will not be detected, unless they are moved out.
+
+If \meta{number list} is presented, the mark classes are these numbers, otherwise
+they are the automatical updating list.
+\end{function}
+
+\begin{function}{\UpdateMarks}
+ \begin{syntax}
+ \verb|\UpdateMarks|
+ \verb|\UpdateMarks| \oarg{number list}
+ \end{syntax}
+Reinserting saved first marks and last marks of specified mark classes
+(if have been saved) into the current box,
+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.
+\end{function}
+
+
+\section{Disable patches or write your own patches}
+
+By default, \pkg{updatemarks} use its own patches to support \env{minipage},
+\env{multicols} and \env{tcolorbox}, however, you can write your own patches and
+remove the patches will be done by \pkg{updatemarks}.
+
+To the patches for \env{minipage}, you can define \tn{updatemarks@minipage@patch}
+before \pkg{updatemarks} is loaded, then \pkg{updatemarks} will use your patches.
+Specially, if you set \tn{updatemarks@minipage@patch} to empty, then no patches will
+be done for \cs{endminipage}.
+
+The patches for \pkg{multicol}, \pkg{adjmulticol} and \pkg{tcolorbox},
+are \tn{updatemarks@multicol@patch}, \tn{updatemarks@adjmulticol@patch},
+\tn{updatemarks@tcolorbox@patch} and \linebreak\tn{updatemarks@multicolnewmark@patch},
+\tn{updatemarks@adjmulticolnewmark@patch} for new mark mechanism,
+you are able set them in preamble before or after \pkg{updatemarks} is loaded.
+
+
+\section{Programming interfaces}
+
+This section describes the interfaces of \LaTeX3.
+
+\begin{function}{\updatemarks_extract:nN,\updatemarks_extract_split:N}
+ \begin{syntax}
+ \verb|\updatemarks_extract:nN| \marg{box 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}.
+
+\meta{box 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.
+
+They only save the marks whose positions are first or last.
+\end{function}
+
+\begin{function}{\updatemarks_update:N}
+ \begin{syntax}
+ \verb|\updatemarks_update:N| \meta{seq var}
+ \end{syntax}
+This function has the same function of \cs{UpdateMarks}.
+
+\meta{seq var} is the number sequence of mark classes which are need to be
+reinserted into the current box or the main vertical list.
+
+It only reinserts marks whose positions are first or last.
+\end{function}
+
+\begin{function}{\updatemarks_save:Nnn}
+ \begin{syntax}
+ \verb|\updatemarks_save: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 expanding \meta{value code} \emph{once}.
+The \meta{value code} receives each item in the \meta{seq var}
+as a trailing brace group.
+\end{function}
+
+\begin{function}{\updatemarks_save_x:Nnn}
+ \begin{syntax}
+ \verb|\updatemarks_save_x: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}.
+The \meta{value code} receives each item in the \meta{seq var}
+as a trailing brace group.
+\end{function}
+
+\begin{function}{\updatemarks_alias:Nnn}
+ \begin{syntax}
+ \verb|\updatemarks_alias:Nnn| \meta{seq var} \marg{alias position} \marg{source position}
+ \end{syntax}
+Setting marks at \meta{alias position} are equal to \meta{source position}
+of specified mark classes \meta{seq var}.
+\end{function}
+
+\begin{function}{\updatemarks_remove:Nn}
+ \begin{syntax}
+ \verb|\updatemarks_remove:Nn| \meta{seq var} \marg{position}
+ \end{syntax}
+Remove marks at \meta{position} of specified mark classes \meta{seq var}.
+\end{function}
+
+\begin{function}[EXP]{\updatemarks_value:nn}
+ \begin{syntax}
+ \verb|\updatemarks_value:nn| \marg{position} \marg{mark class}
+ \end{syntax}
+Return the value of \meta{mark class} at \meta{position}.
+If it has not been saved, then return to total empty.
+
+\begin{texnote}
+ The result is returned within the \tn{unexpanded} primitive (\cs{exp_not:n}).
+\end{texnote}
+\end{function}
+
+\begin{function}{\g_updatemarks_max_int}
+Readonly interger, its value is the maximum mark class number allocated.
+\end{function}
+
+\begin{function}{\g_updatemarks_seq}
+The number sequence which holds the mark classes needed to be automatical updated.
+\end{function}
+
+\begin{function}{\g_updatemarks_classes_seq}
+Readonly number sequence which holds the mark classes allocated by
+\cs{NewMarkClass}. If \cs{NewMarkClass} is undefined, then it's empty.
+\end{function}
+
+
+\end{document} \ No newline at end of file