Debian Codegraph @

texmf-dist/source/latex/widows-and-orphans/widows-and-orphans.dtx

raw
1 % \iffalse meta-comment
2 %%
3 %% File: widows-and-orphans.dtx (C) Copyright 2017-2023 Frank Mittelbach
4 %
5 % It may be distributed and/or modified under the conditions of the
6 % LaTeX Project Public License (LPPL), either version 1.3c of this
7 % license or (at your option) any later version. The latest version
8 % of this license is in the file
9 %
10 % https://www.latex-project.org/lppl.txt
11 %
12 %
13 % The development version of the bundle can be found at
14 %
15 % https://github.com/FrankMittelbach/fmitex/widows-and-orphans
16 %
17 % for those people who are interested.
18 % \fi
19 % \iffalse
20 %<*driver>
21 \RequirePackage[nohyphen]{underscore} % no hyphen after undercore
22 % in csname
23 \documentclass
24 [final]
25 {l3doc-TUB}
26
27 \setcounter{page}{1}
28
29 % fix for _TF undefined,
30 % https://github.com/latex3/latex3/issues/477#issuecomment-419458783
31 \ExplSyntaxOn
32 \cs_set_protected:Npn \__codedoc_typeset_TF:
33 {
34 \group_begin:
35 \exp_args:No \__codedoc_if_macro_internal:nT \l__codedoc_tmpa_tl
36 { \color[gray]{0.5} }
37 \itshape TF
38 \iffalse \makebox[0pt][r]
39 {
40 \color{red}
41 \underline{\phantom{\itshape TF} \kern-0.1em}
42 } \fi
43 \group_end:
44 }
45
46 \NewDocumentCommand \TypesetImplementationTF { m m }
47 {
48 \bool_if:NTF \g__codedoc_typeset_implementation_bool
49 { #1 }
50 { #2 }
51 }
52
53 \ExplSyntaxOff
54
55 \makeatletter % fix for ltugboat issue with doc (if old doc is used)
56 \def\dotfill{\leaders\hbox to.6em{\hss .\hss}\hskip\z@ plus 1fill\kern\z@}%
57 \def\dotfil{\leaders\hbox to.6em{\hss .\hss}\hfil\kern\z@}%
58 \def\pfill{\unskip~\dotfill\penalty500\strut\nobreak
59 \dotfil~\ignorespaces}%
60 \makeatother
61
62 \begin{document}
63
64 \DocInput{widows-and-orphans.dtx}
65 \advance\signaturewidth by 42pt
66 \makesignature
67 \end{document}
68 %</driver>
69 % \fi
70 %
71 % \DoNotIndex{\cs_new:Npn,\cs_new_nopar:Npn,\csname,\endcsname,\fi:,\else:}
72 % \DoNotIndex{\tl_new:N,\bool_new:N}
73 % \DoNotIndex{\if_meaning:w,\iftrue,\int_new:N,\int_set:Nn}
74 % \DoNotIndex{\prop_new:N,\tl_put_left:Nn}
75 % \DoNotIndex{\bool_do_until:Nn,\bool_gset_false:N,\bool_gset_true:N}
76 % \DoNotIndex{\bool_if:NTF,\bool_set_false:N,\bool_set_true:N}
77 % \DoNotIndex{\clist_map_break:n,\clist_map_inline:nn}
78 % \DoNotIndex{\cs_if_eq:NNTF,\exp_args:Nc}
79 % \DoNotIndex{\int_case:nnTF,\int_case:nnF,\int_case:nnF,\int_incr:N}
80 % \DoNotIndex{\int_to_arabic:n,\int_to_roman:n}
81 % \DoNotIndex{\keys_define:nn,\keys_set:nn}
82 % \DoNotIndex{\msg_err:nn,\msg_new:nnnn,\msg_redirect_module:nnn}
83 % \DoNotIndex{\msg_warning:nn,\msg_warning:nnn,\msg_error:nn}
84 % \DoNotIndex{\prop_clear:N,\prop_get:NnNTF,\prop_put:Nnn,\prop_show:N}
85 % \DoNotIndex{\prg_new_conditional:Npnn}
86 % \DoNotIndex{\prg_return_false:,\prg_return_true:}
87 % \DoNotIndex{\prop_get:NVNT,\prop_put:NVn,\bool_if:NF,\bool_if:NT}
88 % \DoNotIndex{\marginpar,\space,\ignorespaces,\thepage}
89 % ^^A\DoNotIndex{\RequirePackage,\NeedsTeXFormat,\NewDocumentCommand}
90 %
91 % \title{The \pkg{widows-and-orphans} package}
92 % \author{Frank Mittelbach}
93 % \date{Printed \today\thanks{For the package version
94 % see the \texttt{\string\ProvidesExplPackage} line in the code.}}
95 % \address{Mainz, Germany}
96 % \netaddress{https://www.latex-project.org}
97 % \personalURL{https://ctan.org/pkg/widows-and-orphans}
98 %
99 % \maketitle
100 %
101 % \begin{abstract}
102 % The \pkg{widows-and-orphans} package checks page or column breaks
103 % for issues with widow or orphan lines and issues warnings if such
104 % problems are detected. In addition, it checks and complains
105 % about breaks involving hyphenated words and warns about display
106 % formulas directly after a page break\Dash if they are allowed by the
107 % document parameter settings, which by default isn't the case.
108 %
109 % A general discussion of the problem of widows and orphans and
110 % suggestions for resolution is given in~\cite{tub-wao}.
111 % \end{abstract}
112 %
113 % \tableofcontents
114 %
115 % \newcommand\option[1]{\texttt{#1}}
116 % \newcommand\ovalue[1]{\texttt{#1}}
117 %
118 % \section{Overview}
119 %
120 % To determine if a widow or orphan has occurred at a column or page
121 % break, the package analyzes the \cs{outputpenalty} that triggered the
122 % break. As \TeX{} adds special penalties to widow and orphan lines
123 % (\cs{widowpenalty} and \cs{clubpenalty}), we can hope to identify
124 % them, provided the penalties have unique values so that we don't end
125 % up with false positives.
126 %
127 % \TypesetImplementationTF {\enlargethispage*{2\baselineskip}}{}
128 %
129 % The package therefore analyzes the different parameter values and if
130 % necessary adjusts the settings slightly so that all possible
131 % combinations that can appear in documents have unique values and can
132 % thus be identified.
133 %
134 % All that remains is to hook into the output routine check;
135 % if \cs{outputpenalty} has a value that matches one of the
136 % problematic cases, issue a warning.
137 %
138 % Besides widows and orphans it is possible to detect other cases
139 % controlled through penalty parameters, e.g., \cs{brokenpenalty} that is
140 % added if a line ends in a hyphen. So by including this parameter
141 % into the checks, we can identify when that happens at the end of a
142 % column and issue a warning there too.
143 %
144 % We also do this for \cs{predisplaypenalty}, which controls a break just
145 % in front of a math display. This is normally set to \texttt{10000}
146 % so such breaks don't happen in standard \LaTeX{}, but if the value
147 % is lowered it becomes possible, and thus a possible issue.
148 %
149 % \subsection{Options}
150 %
151 % The package has a number of key/value options to adjust its
152 % behavior.
153 % The option \option{check} defines what happens
154 % when an issue is found: default is \ovalue{warning}, other
155 % possibilities are \ovalue{error}, \ovalue{info} and \ovalue{none}.
156 %
157 % If the option \option{draft} is given on the document class then the
158 % checking messages are reduced to \ovalue{info} messages and only appear in
159 % the log file. If one wants warnings or errors in that case, one has
160 % to explicitly specify \option{check} with the appropriate value on
161 % the package level.
162 %
163 % The options \option{orphans} and \option{widows} set
164 % reasonable parameter values; the default is to use whatever the class
165 % defines. Possible values are \ovalue{prevent}, \ovalue{avoid} or
166 % \ovalue{default}, the latter meaning use standard \LaTeX{} defaults.
167 %
168 % To set all parameters in one go you can use \option{prevent-all},
169 % \option{avoid-all} or \option{default-all}. These options also assign
170 % values to \cs{brokenpenalty} and \cs{predisplaypenalty}.
171 %
172 % ^^A\TypesetImplementationTF {\pagebreak}{}
173 %
174 %
175 % \subsection{User commands}
176 %
177 % The package provides three user-level commands.
178 %
179 % \vspace*{-4pt}
180 % \begin{function}{\WaOsetup}
181 % \begin{syntax}
182 % \cs{WaOsetup} \meta{comma list}
183 % \end{syntax}
184 % This command accepts any of the package options and allows
185 % adjusting the package behavior in mid-document if necessary.
186 % \end{function}
187
188 % \vspace*{-4pt}
189 % \begin{function}{\WaOparameters}
190 % \begin{syntax}
191 % \cs{WaOparameters}
192 % \end{syntax}
193 % This command produces a listing of the parameter combinations and
194 % their values.
195 % \end{function}
196
197 % \vspace*{-4pt}
198 % \begin{function}{\WaOignorenext}
199 % \begin{syntax}
200 % \cs{WaOignorenext}
201 % \end{syntax}
202 % This command directs the package to not generate warnings for
203 % the current page or columns (if we know that they can't be corrected).
204 % \end{function}
205 %
206 %
207 %
208 % \subsection{Related packages}
209 %
210 % Package \pkg{nowidow}: This package offers some commands to help
211 % pushing lines from one page to another by locally
212 % requesting no widows or orphans\Dash possibly for several lines. In that
213 % respect it implements one of the possibilities discussed in the
214 % \TUB\ article~\cite{tub-wao}. This is, however, in many cases not the
215 % best solution to get rid of a widow or orphan when the interest is
216 % to achieve high typographical quality.
217 %
218 %
219 %
220 % \StopEventually{
221 % \begin{thebibliography}{1}
222 % \bibitem{tub-wao}
223 % Frank Mittelbach.
224 % \newblock Managing forlorn paragraph lines (a.k.a.\ widows and orphans)
225 % in \LaTeX{}.
226 % \newblock \textsl{TUGboat} 39:3,
227 % \ifx\thisissuepageref\undefined \else \thisissuepageref{mitt-widows} ,\fi
228 % 2018.
229 % \bibitem{expl3}
230 % \LaTeX3 Project Team.
231 % \newblock A collection of articles on \pkg{expl3}.\\
232 % \url{https://latex-project.org/publications/indexbytopic/l3-expl3/}
233 % \end{thebibliography}
234 % \ifx\thisissuepageref\undefined ^^A is this TUB production ??? if not gen index
235 % \setlength\IndexMin{200pt} \PrintIndex
236 % \fi
237 % }
238 %
239 %
240 % \section{The implementation}
241 %
242 % The package is implemented in \pkg{expl3}, so the first thing we do
243 % is to define a prefix for our internal commands, so that we can
244 % write \texttt{@@} in the source when we mean the prefix \texttt{__fmwao},
245 % indicating that something is internal.\footnote{\texttt{l3docstrip}
246 % expands that for us, so in the \texttt{.sty} file we get the
247 % longer names with double underscores even though the real source
248 % just contains \texttt{@@} all over the place. The same is done by
249 % the \texttt{l3doc} class for the printed documentation you are
250 % currently reading.\raggedright}
251 %
252 % \begin{macrocode}
253 %<@@=fmwao>
254 % \end{macrocode}
255 %
256 % Then we check that we are running on top of \LaTeXe{} and use a fairly recent
257 % version of the kernel that contains the L3 programming layer,
258 % \pkg{xparse} and the command \cs{ProcessKeyOptions}. For the latter
259 % we need June 2022.
260 % \changes{v1.0f}{2023/04/02}{Require a kernel of 2022-06 or newer}
261 % \begin{macrocode}
262 \NeedsTeXFormat{LaTeX2e}[2022-06-01]
263 % \end{macrocode}
264 %
265 % Then we announce the package to the world at large. This declaration
266 % will also tell \LaTeX{} that this is an \pkg{expl3} package and that
267 % from now on the \pkg{expl3} conventions are to be obeyed, e.g.,
268 % \texttt{_} and \texttt{:} can appear in command names and whitespace
269 % is automatically ignored (so no need for \texttt{\%} all over
270 % the place).\footnote{Figure~\ref{fig:expl3} gives a short
271 % introduction to the naming conventions of \pkg{expl3} for those
272 % readers who haven't seen any code written in \pkg{expl3}.
273 % For more details refer to~\cite{expl3}.}
274 %
275 % \begin{figure}
276 % \centering
277 % \setlength\fboxsep{7pt}
278 % \noindent\hspace{-\marginparwidth}\fbox{\begin{minipage}{1.21\textwidth}
279 % Commands in \pkg{expl3} use the following naming convention:
280 % \begin{tabbing}
281 % \qquad \texttt{\space\space\bslash\meta{module}\_\meta{action}:\meta{arg-spec}}
282 % \quad
283 % \= \% externally available command \\
284 % \qquad \texttt{\bslash\_\_\meta{module}\_\meta{action}:\meta{arg-spec}}
285 % \> \% internal command local to the package
286 % \end{tabbing}
287 %
288 % \vspace*{2pt}
289 %
290 % \begin{description} \raggedright
291 % \item[\ttfamily\meta{module}] describes the (main) area to which
292 % the command belongs,
293 % \item[\ttfamily\meta{action}] describes the (main) action of the
294 % command, and
295 % \item[\ttfamily\meta{arg-spec}] shows the expected command
296 % arguments and their preprocessing:\\
297 % \texttt{N} means expect a
298 % single token; \\
299 % \texttt{n} means expect a (normal) braced
300 % argument;\\
301 % \texttt{T} and \texttt{F} also represent braced
302 % arguments, indicating ``true'' and ``false'' branches in a
303 % conditional; \\
304 % \texttt{V} means expect a single token, interpret it as a
305 % variable and pass its value on to the command;\\
306 % Finally, \texttt{p} stands for a (possibly empty) parameter spec, e.g.,
307 % \texttt{\#1\#2...}\ in a definition.
308 % \\There are a number of other
309 % argument types, but they aren't used in the code described here.
310 % \end{description}
311 %
312 % \vspace*{2pt}
313 %
314 % Examples:
315 % \begin{description} \raggedright
316 % \item[\cs{cs_if_eq:NNTF}] is a conditional from the module
317 % \texttt{cs} (command names) implementing the action \\
318 % \texttt{if\_eq} (if equal) and expecting two single tokens
319 % (commands to compare) and a true and a false branch (one of
320 % which is executed).
321 %
322 % \item[\cs{tl_put_left:Nn}] is a function from the module
323 % \texttt{tl} (token lists) implementing \texttt{put\_left} and \\
324 % expecting a single token (a token list variable) and a braced
325 % argument (the data to insert at \\
326 % the front/left in the variable).
327 % \end{description}
328 %
329 % \medskip
330 %
331 % Variables start with \cs{l_} (for local) or \cs{g_} (for global)
332 % and have the data type as the last part of the name. Variables
333 % internal to the package use two underscores, e.g.,
334 % \cs{l__@@_gen_warn_bool}.
335 %
336 % \end{minipage}}
337 %
338 % \caption{Crash course in \pkg{expl3} command name conventions}
339 % \label{fig:expl3}
340 % \end{figure}
341 %
342 % \begin{macrocode}
343 \ProvidesExplPackage{widows-and-orphans}{2023/04/02}{1.0f}
344 {Detecting widows and orphans (FMi)}
345 % \end{macrocode}
346 %
347 %
348 % \begin{macro}[int]{\@makecol}
349 %
350 % As mentioned in the introduction we want to check the value of
351 % \cs{outputpenalty} inside the output routine, and so we need
352 % to add some code to the output routine.
353 %
354 % We add it to the front of \cs{@makecol}, the macro that
355 % assembles the actual column. This way it only gets executed if we
356 % make a column or a page but not when the output routine is
357 % triggered because of a float or \cs[no-index]{marginpar}.
358 % \begin{macrocode}
359 \tl_put_left:Nn \@makecol { \@@_test_for_widows_etc: }
360 % \end{macrocode}
361 % \end{macro}
362 %
363 %
364 % \subsection{Checking \cs{outputpenalty}}
365 %
366 %
367 % \begin{macro}{\g_@@_gen_warn_bool}
368 % To be able to suppress checking we define a global boolean
369 % variable which by default is set to \texttt{true} (warnings enabled).
370 % \begin{macrocode}
371 \bool_new:N \g_@@_gen_warn_bool
372 \bool_gset_true:N \g_@@_gen_warn_bool
373 % \end{macrocode}
374 % \end{macro}
375 %
376 %
377 %
378 % \begin{macro}{\@@_test_for_widows_etc:}
379 %
380 % What are the different values related to orphans and widows and
381 % the like that can appear in \cs{outputpenalty}? Here is the
382 % basic list:
383 % \begin{description}
384 %
385 % \item[$\cs{widowpenalty} + \cs{interlinepenalty} \to$] if the
386 % break happens on the second-last line of a paragraph and the
387 % paragraph is not followed by a math display.
388 %
389 % \item[$\cs{displaywidowpenalty} + \cs{interlinepenalty} \to$] if
390 % the break happens on the second-last line of a paragraph and the
391 % paragraph is followed by a math display.
392 %
393 % \item[$\cs{clubpenalty} + \cs{interlinepenalty} \to$] if the
394 % break happens after the first line of a paragraph and the
395 % paragraph has more than two lines.
396 %
397 % \item[$\cs{clubpenalty}+\cs{widowpenalty} + \cs{interlinepenalty}
398 % \to$] if the break happens after the first line of a paragraph in
399 % a two-line paragraph (thus this line is also the second-last
400 % line).
401 %
402 % \item[$\cs{clubpenalty}+\cs{displaywidowpenalty} +
403 % \cs{interlinepenalty} \to $] if the
404 % break happens after the first line of a paragraph in a two-line
405 % paragraph and a math display follows.
406 %
407 % \end{description}
408 % That's it for widows and orphans. If we also consider hyphenated
409 % breaks then we get a further set of cases, namely all of the
410 % above with \cs{brokenpenalty} added in and the case of
411 % \cs{brokenpenalty} on its own (with just \cs{interlinepenalty} added).
412 %
413 % \begin{macrocode}
414 \cs_new:Npn \@@_test_for_widows_etc: {
415 % \end{macrocode}
416 % So here is the main test. We compare \cs{outputpenalty} with each
417 % case until we have a hit or run out of cases. Instead of adding
418 % \cs{interlinepenalty} to each case we subtract it once from
419 % \cs{outputpenalty} to make the comparison a little more
420 % efficient.
421 %
422 % If we get a hit, we execute the corresponding code: either
423 % \cs{@@_problem_identified:n} or \cs{@@_problem_identified:nn}
424 % (i.e., one or two arguments) to issue the warning. The arguments
425 % are to select the correct warning text and customize it further
426 % if necessary. For example, in the first case it is a ``widow''
427 % problem and the text in the message should start with
428 % ``\texttt{Widow}'' while in the second case it is also a
429 % ``widow'' problem but the text will say ``\texttt{Display\string~
430 % widow}''.\footnote{If you haven't seen much \pkg{expl3} code you
431 % may wonder about the \texttt{\string~}. As the code ignores
432 % spaces we have to mark up real spaces and for this the tilde is
433 % used. In \pkg{expl3} code this does not act as a tie, but simply
434 % as a catcode 10 space character (while normal spaces are
435 % ignored).} This just saves a bit of space when different cases
436 % share more or less the same message text.
437 % \begin{macrocode}
438 \int_case:nnF { \outputpenalty - \interlinepenalty }
439 {
440 { \widowpenalty }
441 { \@@_problem_identified:nn{widow}{Widow} }
442 { \displaywidowpenalty }
443 { \@@_problem_identified:nn{widow}{Display~ widow} }
444 % \end{macrocode}
445 % Above we have always talked about testing for \cs{clubpenalty}
446 % because that is the register \TeX{} is using. However, \LaTeX{}
447 % changes its value back and forth between \texttt{10000} (after a
448 % heading) and \cs{@clubpenalty} (the saved value) and sometimes
449 % even \texttt{0}. Thus when the output routine is triggered it
450 % could be any of these values and in case it is zero we would get
451 % spurious matches. So for comparison we always test against
452 % \cs{@clubpenalty}.
453 % \begin{macrocode}
454 { \@clubpenalty }
455 { \@@_problem_identified:n{orphan} }
456 { \@clubpenalty + \widowpenalty }
457 { \@@_problem_identified:nn{orphan-widow}{} }
458 { \@clubpenalty + \displaywidowpenalty }
459 { \@@_problem_identified:nn{orphan-widow}{display} }
460 % \end{macrocode}
461 %
462 % A similar issue comes from a hyphen at the end of a column or
463 % page in which case \TeX{} adds \cs{brokenpenalty} so we can test
464 % against that:
465 % \begin{macrocode}
466 { \brokenpenalty }
467 { \@@_problem_identified:n{hyphen} }
468 % \end{macrocode}
469 % However, I said ``\TeX{} adds'', which means if a widow line also
470 % ends in a hyphen then the penalty will be the sum of both
471 % individual penalties. So all the cases above need to be repeated
472 % with \cs{brokenpenalty} added to the value.
473 % We generate the same warnings, though\Dash e.g., we will say ``Widow
474 % detected'' and not ``Hyphenated widow line detected'' as the
475 % latter seems to be overkill.
476 % \begin{macrocode}
477 { \brokenpenalty + \widowpenalty }
478 { \@@_problem_identified:nn{widow}{Widow} }
479 { \brokenpenalty + \displaywidowpenalty }
480 { \@@_problem_identified:nn{widow}{Display~ widow} }
481 { \brokenpenalty + \@clubpenalty }
482 { \@@_problem_identified:n{orphan} }
483 { \brokenpenalty + \@clubpenalty + \widowpenalty }
484 { \@@_problem_identified:nn{orphan-widow}{} }
485 { \brokenpenalty + \@clubpenalty + \displaywidowpenalty }
486 { \@@_problem_identified:nn{orphan-widow}{display} }
487 % \end{macrocode}
488 % Finally there is \cs{predisplaypenalty} that we may as well check also
489 % (in case it was set to a value lower than \texttt{10000}). If it
490 % appears it means we have a display at the very top of the page.
491 % We reuse the ``widow'' warning but this time say
492 % ``\texttt{Lonely\string~ display}'' in the second argument.
493 % This case does not have \cs{interlinepenalty} added by
494 % \TeX{}, so we have to undo the optimization above.
495 % \begin{macrocode}
496 { \predisplaypenalty - \interlinepenalty }
497 { \@@_problem_identified:nn{widow}{Lonely~ display} }
498 }
499 % \end{macrocode}
500 % The last argument of \cs[no-index]{int_case:nnF} is executed in
501 % the ``false'' case, i.e., when no match has been found. In that
502 % case we check the status of \cs{g_@@_gen_warn_bool} and
503 % if that is also ``false'', i.e., we have been asked not to
504 % generate warnings, we issue an error message. Why? Because
505 % the user asked us explicitly to ignore problems on the
506 % current page, but we found nothing wrong. This either means a
507 % problem got corrected or the request was intended for a
508 % different page. Either way it is probably worth checking.
509 %
510 % \begin{macrocode}
511 { \bool_if:NF \g_@@_gen_warn_bool
512 { \msg_error:nn{widows-and-orphans}{no-problem} } }
513 % \end{macrocode}
514 % Finally, we make sure that the next page or column is again
515 % checked.
516 % \begin{macrocode}
517 \bool_gset_true:N \g_@@_gen_warn_bool
518 }
519 % \end{macrocode}
520 % \end{macro}
521
522
523
524 % \begin{macro}{\@@_problem_identified:n}
525 % \begin{macro}{\@@_problem_identified:nn}
526 % These commands prepare for generating a warning, but only if we
527 % are supposed to, i.e., if \cs{g_@@_gen_warn_bool} is true.
528 % \begin{macrocode}
529 \cs_new:Npn \@@_problem_identified:n #1 {
530 \bool_if:NT \g_@@_gen_warn_bool
531 { \msg_warning:nn{widows-and-orphans}{#1} }
532 }
533 \cs_new:Npn \@@_problem_identified:nn #1 #2 {
534 \bool_if:NT \g_@@_gen_warn_bool
535 { \msg_warning:nnn{widows-and-orphans}{#1}{#2} }
536 }
537 % \end{macrocode}
538 % \end{macro}
539 % \end{macro}
540
541
542 % \subsection{Messages to the user}
543 %
544 %
545 % \begin{macro}{\@@_this_page:}
546 % \begin{macro}{\@@_next_page:}
547 % For displaying nice messages to the user we need a few helper
548 % commands. The two here show the page number of the current or
549 % next page. They are semi-smart, that is they will recognize
550 % if the document uses roman numerals and if so display the number
551 % as a roman numeral (but in all other cases it uses arabic numerals).
552 % \begin{macrocode}
553 \cs_new:Npn \@@_this_page: { \@@_some_page:n \c@page }
554 \cs_new:Npn \@@_next_page: { \@@_some_page:n { \c@page + 1 } }
555 % \end{macrocode}
556 % \end{macro}
557 % \end{macro}
558
559
560 % \begin{macro}{\@@_some_page:n}
561 % \begin{macro}{\@@_roman_thepage:}
562 % This macro first compares \cs[no-index]{thepage} against the code that
563 % would be used in the case of a roman numeral representation, and then
564 % displays its argument using either arabic numbers or roman numerals.
565 % \begin{macrocode}
566 \cs_new:Npn \@@_some_page:n #1 {
567 \cs_if_eq:NNTF \thepage \@@_roman_thepage:
568 { \int_to_roman:n } { \int_to_arabic:n }
569 { #1 }
570 }
571 % \end{macrocode}
572 % \cs{@@_roman_thepage:} just stores the default definition of
573 % \cs[no-index]{thepage} if page numbers are represented by roman numerals
574 % for use in the comparison above.
575 % \begin{macrocode}
576 \cs_new_nopar:Npn \@@_roman_thepage: {\csname @roman\endcsname \c@page}
577 % \end{macrocode}
578 % \end{macro}
579 % \end{macro}
580
581
582
583
584 % \begin{macro}[TF, int]{\legacy_switch_if:n}
585 % To evaluate \LaTeXe{} boolean switches in a nice way, we need a
586 % conditional. Eventually this will probably make it into the \pkg{expl3}
587 % code in this or a similar form, but right now it is missing.
588 % \begin{macrocode}
589 \prg_new_conditional:Npnn \legacy_switch_if:n #1 {p, T , F , TF }
590 { \exp_args:Nc\if_meaning:w { if#1 } \iftrue \prg_return_true:
591 \else: \prg_return_false: \fi: }
592 % \end{macrocode}
593 % \end{macro}
594 %
595 %
596 %
597 %
598 % The first message is issued if we have been directed to ignore a
599 % problem and there wasn't one:{\hfuzz=14.1pt
600 % \begin{macrocode}
601 \msg_new:nnnn {widows-and-orphans} {no-problem}
602 { No~ problem~ to~ suppress~ on~ this~ page! }
603 { Suppression~ of~ a~ widow~ or~ orphan~ problem~ was~ requested~
604 but~ on~ the~ current~ page~ there~ doesn't~ seem~ to~ be~ any.~
605 Maybe~ the~ text~ was~ changed~ and~ the~ request~ should~ get~
606 (re)moved?}
607 % \end{macrocode}
608 % }
609 %
610 % \bigskip
611 %
612 %
613 %
614 %
615 % The next message is about orphans. They can appear at the bottom of
616 % the first or the second column of the current page, if we are in
617 % two-column mode. So we check for this and adjust the message accordingly.
618 % \begin{macrocode}
619 \msg_new:nnnn {widows-and-orphans} {orphan}
620 { Orphan~ on~ page~ \@@_this_page:
621 \legacy_switch_if:nT {@twocolumn}
622 { \space ( \legacy_switch_if:nTF {@firstcolumn}
623 { first~ } { second~ } column) }
624 }
625 { Check~ out~ the~ page~ and~ see~ if~ you~ can~ avoid~ the~ orphan.}
626 % \end{macrocode}
627 %
628 %
629 % \bigskip
630 %
631 %
632 % A hyphen at the end of a page or column requires more or less the
633 % same message, so this could have been combined with the previous one.
634 % \begin{macrocode}
635 \msg_new:nnnn {widows-and-orphans} {hyphen}
636 { Hyphen~ in~ last~ line~ of~ page~ \@@_this_page:
637 \legacy_switch_if:nT {@twocolumn}
638 { \space ( \legacy_switch_if:nTF {@firstcolumn}
639 { first~ } { second~ } column) }
640 }
641 { Check~ out~ the~ page~ and~ see~ if~ you~ can~ get~
642 a~ better~ line~ break. }
643 % \end{macrocode}
644 %
645 %
646 % \bigskip
647 %
648 %
649 % Widows need a different logic since we detect them when cutting a
650 % previous page or column but the widow is on the following one.
651 % This message works for ``widows'', ``display widows'' as well as
652 % math displays by just changing the first word (or words), so here
653 % we use an additional argument:
654 % \begin{macrocode}
655 \msg_new:nnnn {widows-and-orphans} {widow}
656 { #1~ on~ page~
657 \legacy_switch_if:nTF {@twocolumn}
658 { \legacy_switch_if:nTF {@firstcolumn}
659 { \@@_this_page: \space (second~ }
660 { \@@_next_page: \space (first~ }
661 column)
662 }
663 { \@@_next_page: }
664 }
665 { Check~ out~ the~ page~ and~ see~ if~ you~ can~ avoid~ the~ widow.}
666 % \end{macrocode}
667 %
668 %
669 % \bigskip
670 %
671 %
672 % The case of both widow and orphan is similar, but we obviously
673 % need different text so we made it its own message.
674 % \begin{macrocode}
675 \msg_new:nnnn {widows-and-orphans} {orphan-widow}
676 { Orphan~
677 \legacy_switch_if:nTF {@twocolumn}
678 { \legacy_switch_if:nTF {@firstcolumn}
679 { and~ #1 widow~ on~ page~ \@@_this_page: \space
680 (first~ and~ second~ }
681 { on~ page~ \@@_this_page: \space (second~ column)~
682 and~ #1 widow~ on~ page~ \@@_next_page: \space (first~ }
683 }
684 { on~ page~ \@@_this_page: \space (second~ column)~
685 and~ #1 widow~ on~ page~ \@@_next_page: \space (first~ }
686 column)
687 }
688 { Check~ out~ the~ page~ and~ see~ if~ you~ can~ avoid~ both~
689 orphan~ and~ widow.}
690 % \end{macrocode}
691 %
692 %
693 %
694 %
695 %
696 %
697 % \subsection{Adjusting parameter values}
698 %
699 % To avoid (a lot of) false positives during checking it is important
700 % that the parameter values are chosen in a way that all possible
701 % combinations lead to unique \cs{outputpenalty} values. At the same
702 % time, we want them to be as close as possible to the values that
703 % have been initially requested by the user (or in the document class)
704 % and if we deviate too much then this will likely alter the
705 % page breaks \TeX{} finds.
706 % So here is an outline of how we handle the parameters:
707 % \begin{itemize}
708 % \item We set up a property list to hold penalty values that
709 % can appear in \cs{outputpenalty} inside the output routine. The
710 % penalties are the ``keys'' and the corresponding property list value is
711 % the source of how they got produced. For example, the key might be
712 % \texttt{150} and the value \cs{widowpenalty}.
713 %
714 % \item Initially the property list is empty. So adding the first item
715 % simply means taking the value of one parameter, say \texttt{150}
716 % from $\cs{widowpenalty}+\cs{interlinepenalty}$, as the key and
717 % this formula as the property list value.
718 %
719 % \item For the next parameter, say \cs{@clubpenalty}, we check if its
720 % value (or more precisely its value plus \cs{interlinepenalty}) is
721 % already a key in the property list. If that is the case, then we
722 % have failed and must modify the parameter value somehow.
723 %
724 % \item If not, we also have to check any combination of the current
725 % parameter with any parameter processed earlier. If that
726 % combination is possible, e.g., \cs{@clubpenalty} (new) and
727 % \cs{widowpenalty} (already processed) then we also have to check
728 % the sum. If that sum is already a key in the property list then
729 % we have failed as well.
730 %
731 % \item If we have failed, we iterate by incrementing the current parameter
732 % value and try again. Eventually we will get to a value where all
733 % combinations we test work, that is, are not yet in the property list.
734 %
735 % \item We then change the parameter to this value and add all the
736 % combinations we tried before to the property list (that is
737 % $\cs{@clubpenalty}+\cs{interlinepenalty}$ both alone and together with
738 % \cs{widowpenalty} in our example). Thus from now on those are
739 % also forbidden values.
740 %
741 % \item We do all this with a helper command that takes the new
742 % parameter as the first argument and the list of different cases
743 % to try as a comma-separated list as a second argument, e.g.,
744 %\begin{verbatim}
745 % \__fmwao_decide_penalty:Nn \@clubpenalty
746 % { \@clubpenalty + \interlinepenalty ,
747 % \@clubpenalty + \widowpenalty + \interlinepenalty }
748 %\end{verbatim}
749 %
750 % \item This way we are adding all relevant parameters to the property
751 % list and at the same time adjusting their values if needed.
752 % \item Once all parameters are handled the property list is no longer
753 % needed as the parameters got changed along the way, but we keep it
754 % around as it allows for a simple display of all settings in one go.
755 % \end{itemize}
756 %
757 %
758
759 % \begin{macro}{\l_@@_penalties_prop}
760 % Here is the property list for our process.
761 % \begin{macrocode}
762 \prop_new:N \l_@@_penalties_prop
763 % \end{macrocode}
764 % \end{macro}
765 %
766 %
767 % \begin{macro}{\@@_initialize:}
768 % Now we are ready to go. The first action is to clear the property
769 % list as the initialization may happen several times.
770 % \begin{macrocode}
771 \cs_new:Npn \@@_initialize: {
772 \prop_clear:N \l_@@_penalties_prop
773 % \end{macrocode}
774 % When \TeX{} breaks a page at a glue item with no explicit penalty involved
775 % it sets \cs{outputpenalty} to \texttt{10000} in the output
776 % routine to distinguish it from a case where an explicit penalty of
777 % \texttt{0} was in the document. That means none of our parameters
778 % or parameter combinations can be allowed to have that particular
779 % value, because otherwise we would get a false match for each break
780 % at glue and report an issue. So we enter that value first (by
781 % hand) so that it will not be used by a parameter or parameter
782 % combination.
783 % \begin{macrocode}
784 \prop_put:Nnn \l_@@_penalties_prop {10000} {break~ at~ glue}
785 % \end{macrocode}
786 % The next thing is to add the values for \cs{@lowpenalty},
787 % \cs{@medpenalty}, \cs{@highpenalty} to the property list as
788 % they also may show up in \cs{outputpenalty} if a user says, for
789 % example, \verb=\nopagebreak[2]=.
790 %
791 % Such a penalty from an explicit page break request does not get
792 % \cs{interlinepenalty} added in.
793 % \begin{macrocode}
794 \@@_decide_penalty:Nn \@lowpenalty { \@lowpenalty}
795 \@@_decide_penalty:Nn \@medpenalty { \@medpenalty}
796 \@@_decide_penalty:Nn \@highpenalty { \@highpenalty}
797 % \end{macrocode}
798 % Then comes the first real parameter for the orphans:
799 % \begin{macrocode}
800 \@@_decide_penalty:Nn \@clubpenalty
801 { \@clubpenalty + \interlinepenalty }
802 % \end{macrocode}
803 % followed by the one for the widows and the one for the display widows:
804 % \begin{macrocode}
805 \@@_decide_penalty:Nn \widowpenalty
806 { \widowpenalty + \interlinepenalty ,
807 \widowpenalty + \@clubpenalty + \interlinepenalty }
808
809 \@@_decide_penalty:Nn \displaywidowpenalty
810 { \displaywidowpenalty + \interlinepenalty ,
811 \displaywidowpenalty + \@clubpenalty + \interlinepenalty }
812 % \end{macrocode}
813 % \cs{brokenpenalty} can appear on its own, and also with each and
814 % every combination we have seen so far:
815 % \begin{macrocode}
816 \@@_decide_penalty:Nn \brokenpenalty
817 { \brokenpenalty + \interlinepenalty ,
818 \brokenpenalty + \@clubpenalty + \interlinepenalty ,
819 \brokenpenalty + \widowpenalty + \interlinepenalty ,
820 \brokenpenalty + \widowpenalty + \@clubpenalty + \interlinepenalty ,
821 \brokenpenalty + \displaywidowpenalty + \@clubpenalty
822 + \interlinepenalty }
823 % \end{macrocode}
824 % Finally we have the parameter for lonely displays (again without
825 % \cs{interlinepenalty} being added):
826 % \begin{macrocode}
827 \@@_decide_penalty:Nn \predisplaypenalty { \predisplaypenalty }
828 }
829 % \end{macrocode}
830 % If we run the above code with \LaTeX's default parameter settings
831 % in force it will make a few adjustments and the property list
832 % will afterwards contain
833 % the following entries:
834 %\begin{small}
835 %\begin{verbatim}
836 % The property list \l__fmwao_penalties_prop contains the pairs (without
837 % outer braces):
838 % > {10000} => {break at glue}
839 % > {51} => {\@lowpenalty }
840 % > {151} => {\@medpenalty }
841 % > {301} => {\@highpenalty }
842 % > {150} => {\@clubpenalty +\interlinepenalty }
843 % > {152} => {\widowpenalty +\interlinepenalty }
844 % > {302} => {\widowpenalty +\@clubpenalty +\interlinepenalty }
845 % > {50} => {\displaywidowpenalty +\interlinepenalty }
846 % > {200} => {\displaywidowpenalty +\@clubpenalty +\interlinepenalty }
847 % > {100} => {\brokenpenalty +\interlinepenalty }
848 % > {250} => {\brokenpenalty +\@clubpenalty +\interlinepenalty }
849 % > {252} => {\brokenpenalty +\widowpenalty +\interlinepenalty }
850 % > {402} => {\brokenpenalty +\widowpenalty +\@clubpenalty +\interlinepenalty }
851 % > {300} => {\brokenpenalty +\displaywidowpenalty +\@clubpenalty
852 % +\interlinepenalty }
853 % > {10001} => {\predisplaypenalty }.
854 %\end{verbatim}
855 %\end{small}
856 % \end{macro}
857 %
858 %
859 % \begin{macro}{\l_@@_tmp_int}
860 % \begin{macro}{\l_@@_tmp_tl}
861 % \begin{macro}{\l_@@_success_bool}
862 % For doing the calculations and insertions into the
863 % property list, we will also need an integer register, a token list
864 % variable and another boolean variable.
865 % \begin{macrocode}
866 \int_new:N \l_@@_tmp_int
867 \tl_new:N \l_@@_tmp_tl
868 \bool_new:N \l_@@_success_bool
869 % \end{macrocode}
870 % \end{macro}
871 % \end{macro}
872 % \end{macro}
873 %
874 %
875 % \begin{macro}{\@@_decide_penalty:Nn}
876 % This is the core command that does the real work of choosing values.
877 % Let's recall that its first
878 % argument is the parameter we are currently handling and the
879 % second argument is a comma-separated list of cases for which we
880 % need to ensure that their results are not yet in the property list.
881 % \begin{macrocode}
882 \cs_new:Npn \@@_decide_penalty:Nn #1 #2 {
883 % \end{macrocode}
884 % We start by setting the boolean to \texttt{false} and then run a
885 % loop until we have found a suitable parameter value that meets
886 % our criteria.
887 % \begin{macrocode}
888 \bool_set_false:N \l_@@_success_bool
889 \bool_do_until:Nn \l_@@_success_bool
890 % \end{macrocode}
891 % Inside the loop we start with the assumption that the current
892 % value of the parameter is fine and then check if that assumption
893 % is true. If yes, we can exit the loop, otherwise we will have to
894 % try with a different value.
895 % \begin{macrocode}
896 { \bool_set_true:N \l_@@_success_bool
897 % \end{macrocode}
898 % For the verification we try each item in the second parameter to
899 % see if that is already in the property list.
900 % This means evaluating the expression to get the penalty value
901 % and then looking it up in the property list. If it is there, we
902 % have failed. In this case we set the boolean back to false and
903 % break out of the loop over the second argument since there is
904 % no point in testing further.
905 % \begin{macrocode}
906 \clist_map_inline:nn { #2 }
907 { \int_set:Nn \l_@@_tmp_int {##1}
908 \prop_get:NVNT
909 \l_@@_penalties_prop \l_@@_tmp_int \l_@@_tmp_tl
910 { \clist_map_break:n {\bool_set_false:N\l_@@_success_bool} }
911 }
912 % \end{macrocode}
913 % Once we have finished, the boolean will tell us if we are
914 % successful so far. If yes, it means there was no conflict. We
915 % therefore add all combinations with this parameter to the
916 % property list, as from now on they are forbidden as well.
917 %
918 %
919 % So we
920 % map once more over the second argument and enter them:
921 % \begin{macrocode}
922 \bool_if:NTF \l_@@_success_bool
923 { \clist_map_inline:nn { #2 }
924 { \int_set:Nn \l_@@_tmp_int {##1}
925 \prop_put:NVn \l_@@_penalties_prop \l_@@_tmp_int {##1}
926 } }
927 % \end{macrocode}
928 % If we failed we increment the parameter value and retry:
929 % \begin{macrocode}
930 { \int_incr:N #1 }
931 }
932 }
933 % \end{macrocode}
934 %
935 %
936 % One place where we will run this code is at the beginning of the
937 % document (so that changes to the parameters in the document class or
938 % the preamble are picked up). The other place is when the
939 % user changes any of the parameters in the middle of the document
940 % via \cs{WaOsetup}.
941 % \begin{macrocode}
942 \AtBeginDocument { \@@_initialize: }
943 % \end{macrocode}
944 %
945 % \end{macro}
946 %
947 % \subsection{The option setup}
948 %
949 % The options are fairly straightforward:
950 %
951 % \begin{macrocode}
952 \keys_define:nn {fmwao} {
953 % \end{macrocode}
954 % By default messages are given as warnings above. If anything else
955 % is wanted the option \option{check} can be used which simply
956 % changes the message class used internally:
957 % \begin{macrocode}
958 ,check .choice:
959 ,check / error
960 .code:n = \msg_redirect_module:nnn {widows-and-orphans}{warning}{error}
961 ,check / info
962 .code:n = \msg_redirect_module:nnn {widows-and-orphans}{warning}{info}
963 ,check / none
964 .code:n = \msg_redirect_module:nnn {widows-and-orphans}{warning}{none}
965 ,check / warning
966 .code:n = \msg_redirect_module:nnn {widows-and-orphans}{warning}{ }
967 % \end{macrocode}
968 % If the class option \texttt{draft} was given we downgrade the
969 % checks to info, thus if one wants warnings or errors even then,
970 % then one has to give the check key explicitly on package level.
971 % \changes{v1.0f}{2023/04/02}{Honor a global draft option (gh/1)}
972 % \begin{macrocode}
973 ,draft .meta:n = {check = info}
974 % \end{macrocode}
975 %
976 % The other options set parameters to some hopefully ``reasonable''
977 % values\Dash no real surprises here. \LaTeX{} internally uses
978 % \cs{@clubpenalty} so we need to set this too, if we change
979 % \cs{clubpenalty}.
980 % \begin{macrocode}
981 ,orphans .choice:
982 ,orphans / prevent .code:n = \int_set:Nn \clubpenalty { 10000 }
983 \int_set:Nn \@clubpenalty { \clubpenalty }
984 ,orphans / avoid .code:n = \int_set:Nn \clubpenalty { 5000 }
985 \int_set:Nn \@clubpenalty { \clubpenalty }
986 ,orphans / default .code:n = \int_set:Nn \clubpenalty { 150 }
987 \int_set:Nn \@clubpenalty { \clubpenalty }
988 % \end{macrocode}
989 %
990 % \begin{macrocode}
991 ,widows .choice:
992 ,widows / prevent .code:n = \int_set:Nn \widowpenalty { 10000 }
993 ,widows / avoid .code:n = \int_set:Nn \widowpenalty { 5000 }
994 ,widows / default .code:n = \int_set:Nn \widowpenalty { 150 }
995 % \end{macrocode}
996 %
997 % \begin{macrocode}
998 ,hyphens .choice:
999 ,hyphens / prevent .code:n = \int_set:Nn \brokenpenalty { 10000 }
1000 ,hyphens / avoid .code:n = \int_set:Nn \brokenpenalty { 2000 }
1001 ,hyphens / default .code:n = \int_set:Nn \brokenpenalty { 50 }
1002 ,prevent-all .code:n = \int_set:Nn \clubpenalty { 10000 }
1003 \int_set:Nn \widowpenalty { 10000 }
1004 \int_set:Nn \displaywidowpenalty{ 10000 }
1005 \int_set:Nn \brokenpenalty { 10000 }
1006 \int_set:Nn \predisplaypenalty { 10000 }
1007 \int_set:Nn \@clubpenalty { \clubpenalty }
1008 % \end{macrocode}
1009 % As an exception, \option{avoid-all} doesn't set
1010 % \cs{predisplaypenalty}; maybe it should.
1011 % \begin{macrocode}
1012 ,avoid-all .code:n = \int_set:Nn \clubpenalty { 5000 }
1013 \int_set:Nn \widowpenalty { 5000 }
1014 \int_set:Nn \displaywidowpenalty { 2000 }
1015 \int_set:Nn \brokenpenalty { 2000 }
1016 % \int_set:Nn \predisplaypenalty { 9999 }
1017 \int_set:Nn \@clubpenalty { \clubpenalty }
1018 % \end{macrocode}
1019 % \option{default-all} reverts back to the standard \LaTeX{}
1020 % default values:
1021 % \begin{macrocode}
1022 ,default-all .code:n = \int_set:Nn \clubpenalty { 150 }
1023 \int_set:Nn \widowpenalty { 150 }
1024 \int_set:Nn \displaywidowpenalty { 50 }
1025 \int_set:Nn \brokenpenalty { 100 }
1026 \int_set:Nn \predisplaypenalty { 10000 }
1027 \int_set:Nn \@clubpenalty { \clubpenalty }
1028 }
1029 % \end{macrocode}
1030 % Once declared we evaluate the options given to the package:
1031 % \changes{v1.0f}{2023/04/02}{Use kernel method now not \pkg{l3keys2e}}
1032 % \begin{macrocode}
1033 \ProcessKeyOptions[fmwao]
1034 % \end{macrocode}
1035 %
1036 %
1037 % \subsection{Document-level commands}
1038 %
1039 % Finally we declare the user-level commands:
1040 %
1041
1042 % \begin{macro}{\WaOsetup}
1043 % This runs the key setup on the first argument and then
1044 % reinitializes the parameter setup:
1045 % \begin{macrocode}
1046 \NewDocumentCommand\WaOsetup{m}
1047 { \keys_set:nn{fmwao}{#1} \@@_initialize: \ignorespaces }
1048 % \end{macrocode}
1049 % \end{macro}
1050 %
1051 %
1052
1053 % \begin{macro}{\WaOparameters}
1054 % This parameterless command outputs a display of the
1055 % current parameter settings.
1056 % \begin{macrocode}
1057 \NewDocumentCommand\WaOparameters{}{\prop_show:N \l_@@_penalties_prop}
1058 % \end{macrocode}
1059 % \end{macro}
1060 %
1061 %
1062 % \begin{macro}{\WaOignorenext}
1063 % And here is the command that suppresses any warning on the
1064 % current page or column:
1065 % \begin{macrocode}
1066 \NewDocumentCommand\WaOignorenext{}
1067 { \bool_gset_false:N \g_@@_gen_warn_bool }
1068 % \end{macrocode}
1069 % \end{macro}
1070 %
1071 % \small\Finale
1072 %
1073
1074 \endinput