summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/updatemarks/doc/updatemarks.tex
blob: 2de3b6bded3c4d9bd7f2b70449696a22b586637e (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
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}