summaryrefslogtreecommitdiff
path: root/macros/luatex/generic/lua-widow-control/lwc-manual.tex
blob: 7d68de6201a74d12c0d7cd8b14e1fb6c536b1cd2 (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
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
% lua-widow-control
% https://github.com/gucci-on-fleek/lua-widow-control
% SPDX-License-Identifier: MPL-2.0+ OR CC-BY-SA-4.0+
% SPDX-FileCopyrightText: 2022 Max Chernoff

\doifnot{\contextmark}{LMTX}{
    \errhelp{LMTX/MkXL is required to compile this file.}
    \errmessage{Fatal error, exiting.}
}

\environment lwc-manual

\usemodule[lua-widow-control]
\usebtxdataset[\jobname.bib]

\useURL[projecturl][https://github.com/gucci-on-fleek/lua-widow-control]
\useURL[download][https://github.com/gucci-on-fleek/lua-widow-control/releases/latest]
\useURL[ctan][https://www.ctan.org/pkg/lua-widow-control]

% Abbreviations
\def\lwc/{\sans{lua-\allowbreak widow-\allowbreak control}}
\def\Lwc/{\sans{Lua-\allowbreak widow-\allowbreak control}}
\def\estretch/{\tex{emergency\allowbreak stretch}}
\def\openalty/{\tex{output\allowbreak penalty}}
\def\waos/{widows and orphans}
\def\wao/{widow and orphan}
\def\woo/{widow or orphan}
\def\mkxl/{\ConTeXt~Mk\acronym{XL}}
\def\mkiv/{\ConTeXt~Mk\acronym{IV}}
\define\OpTeX{Op\kern-.05em\TeX}
\def\LuaMetaTeX{LuaMeta\TeX}
\def\plainop/{Plain~\TeX{}/\OpTeX{}}
\let\q=\quotation

\def\titlecite[#1]{\cite[title][#1]\cite[#1]}

\definetype[inlineTEX][option=tex, escape={$,$}, lines=hyphenated]
\definetype[inlineLUA][option=lua, escape={$,$}, lines=hyphenated]

\input lwc-sample

\startdocument[
    title=lua-widow-control,
    author=Max Chernoff,
    version=2.1.1, %%version
    github=https://github.com/gucci-on-fleek/lua-widow-control,
    ctan=https://www.ctan.org/pkg/lua-widow-control,
]

\Lwc/ is a Plain~\TeX/\LaTeX/\ConTeXt{}/\OpTeX{} package that removes \waos/ without any user intervention. Using the power of \LuaTeX{}, it does so \emph{without} stretching any glue or shortening any pages or columns. Instead, \lwc/ automatically lengthens a paragraph on a page or column where a \woo/ would otherwise occur.

\section{Quick Start}
Ensure that your \TeX~Live/Mik\TeX{} distribution is up-to-date. Then, \LaTeX{} users just need to place \inlineTEX{\usepackage{lua-widow-control}} in the preamble of their document. For more details, see the \goto{Usage sections}[sec:usage].

\subject{Contents}
\placecontent[criterium=all]

\section{Preliminaries}

This manual begins with a brief introduction to widows, orphans, and \lwc/. For an extended introduction and discussion of these topics, please see the \emph{TUGboat} article\cite[article] distributed with this manual (Links: \goto{local}[tb133chernoff-widows::], \goto{\acronym{CTAN}}[url(http://mirrors.ctan.org/macros/luatex/generic/lua-widow-control/tb133chernoff-widows.pdf)], \goto{GitHub}[url(https://github.com/gucci-on-fleek/lua-widow-control/releases/latest/download/tb133chernoff-widows.pdf)]). You can also skip ahead to the \goto{installation instructions on \at{page}[sec:install]}[sec:install] or the \goto{usage section starting at \at{page}[sec:usage]}[sec:usage].

\section[sec:motivation]{Motivation}

Unmodified \TeX{} has only two familiar ways of dealing with \waos/: it can
either shorten a page by one line, or it can stretch vertical
whitespace. \TeX{} was designed for mathematical and scientific typesetting,
where a typical page has multiple section headings, tables, figures, and
equations. For this style of document, \TeX's default behaviour works quite
well, since the slight stretching of whitespace between the various document
elements is nearly imperceptible; however, for prose or other documents
composed almost entirely of paragraphs, there is little vertical whitespace
to stretch.

\Lwc/ offers an alternative method of removing \waos/: instead of shortening a page or stretching vertical whitespace, \lwc/ simply chooses a paragraph to lengthen by one~line such that the \woo/ is eliminated.

\section{Widows and Orphans}
\subsection{Widows}
A \q{widow} occurs when the majority of a paragraph is on one page or column,
but the last line is on the following page or column. It not only looks
quite odd for a lone line to be at the start of the page, but it makes a
paragraph harder to read since the separation of a paragraph and
its last line disconnects the two, causing the reader to lose context for
the widowed line.

\subsection{Orphans}
An \q{orphan} occurs when the first line of a paragraph is at the end
of the page or column preceding the remainder of the paragraph. They are not
as distracting for the reader, but they are still not ideal.
Visually, \waos/ are about equally disruptive; however, orphans tend not to
decrease the legibility of a text as much as widows, so some authors choose
to ignore them.

\subsection{Broken Hyphens}
\q{Broken} hyphens occur whenever a page break occurs in a
hyphenated word. These are not related to \waos/; however,
breaking a word across two pages is at least as disruptive for the reader
as \waos/. \TeX{} identifies broken hyphens in the same ways as \waos/, so
\lwc/ treats broken hyphens in the same way.

\startplacefigure[location={here, top, bottom}, title={A visual comparison of \waos/.}, reference=tab:widow]
    \getbuffer[widow-orphan]
\stopplacefigure

\section{\TeX's Pagination}
\subsection{Algorithm}
It is tricky to understand how \lwc/ works if you aren't familiar with how
\TeX{} breaks pages and columns. For a full description, you should
consult Chapter~15 of \titlecite[texbook] (\q{How \TeX{} Makes Lines
into Pages}); however, this goes into much more detail than most users
require, so here is a \emph{very} simplified summary of \TeX{}'s page
breaking algorithm:

\TeX{} fills the page with lines and other objects until the next object
will no longer fit. Once no more objects will fit, \TeX{} will align the
bottom of the last line with the bottom of the page by stretching any
available vertical spaces if (in \LaTeX) \tex{flushbottom} is set;
otherwise, it will
break the page and leave the bottom empty.

However, some objects have \q{penalties} attached. Penalties encourage or
discourage page breaks from occurring at specific places. For example,
\LaTeX{} sets a negative penalty before section headings to encourage a
page break there; conversely, it sets a positive penalty after section
headings to discourage breaking.

To reduce \waos/, \TeX{} sets weakly-positive penalties between the
first and second lines of a paragraph to prevent orphans, and between the
penultimate and final lines to prevent widows.

\subsection{Behaviour}

Due to these \q{penalties} attached to \waos/, \TeX{} tries to avoid
creating them. Widows and orphans with small penalties attached---like
\LaTeX's default values of 150---are only lightly coupled to the rest
of the paragraph, while \waos/ with large penalties---values of
10\,000 or more---are treated as infinitely bad and are thus
unbreakable. Intermediate values behave just as you would expect,
discouraging page breaks proportional to their value.

However, when these lines are moved as a group, \TeX{} will have to make a page or column with less lines. \about[sec:demo] goes into further detail about how \TeX{} deals with these too-short pages or columns.

\startpostponing
\startTEXpage[
    align=normal,
    width=100cm,
    autowidth=force,
    offset=5pt,
    pagestate=start,
]
    \veryraggedcenter
    \setupTABLE[row][first][style=\ssbf, align=middle]
    \setupTABLE[frame=off, offset=5pt]
    \startTABLE
        \NC Ignore
        \NC Shorten
        \NC Stretch
        \NC \Lwc/ \NC\NR

        \NC \typesetbuffer[ignore][frame=on,page=1]
        \NC \typesetbuffer[shorten][frame=on,page=1]
        \NC \typesetbuffer[stretch][frame=on,page=1]
        \NC \typesetbuffer[lwc][frame=on,page=1]
        \NC\NR

        \NC \typesetbuffer[ignore][frame=on,page=2]
        \NC \typesetbuffer[shorten][frame=on,page=2]
        \NC \typesetbuffer[stretch][frame=on,page=2]
        \NC \typesetbuffer[lwc][frame=on,page=2]
        \NC\NR

        \NC \typebuffer[ignore-code][option=TEX]
        \NC \typebuffer[shorten-code][option=TEX]
        \NC \typebuffer[stretch-code][option=TEX]
        \NC \typebuffer[lwc-code][option=TEX]
        \NC\NR
    \stopTABLE

    \placefloatcaption[table][reference=tab:demo, title={A visual comparison of various automated widow handling techniques.}]
\stopTEXpage
\stoppostponing

\section[sec:demo]{Demonstration}

Although \TeX{}'s page breaking algorithm is reasonably
straightforward, it can lead to
complex behaviour when \waos/ are involved. The usual
choices, when rewriting is not possible, are to ignore them,
stretch some glue, or shorten the
page. \in{Table}[tab:demo] has a visual comparison of these
options, which we'll discuss in the following:

\subsection{\q{Ignore}}

As you can see, the last line of the page is on a separate page from the
rest of its paragraph, creating a widow. This is usually highly
distracting for the reader, so it is best avoided for the reasons previously
discussed.

\subsection{\q{Shorten}}

This page did not leave any widows, but it did shorten the previous page
by one line. Sometimes this is acceptable, but usually it looks bad because
pages will then have different text-block heights. This can make the pages
look quite uneven, especially when typesetting with columns or in a book
with facing pages.

\subsection{\q{Stretch}}

This page also has no widows and it has a flush bottom margin. However,
the space between each pair of paragraphs had to be stretched.

If this page had many equations, headings, and other elements with
natural space between them, the stretched out space would be much less
noticeable. \TeX{} was designed for mathematical typesetting, so it makes
sense that this is its default behaviour. However, in a page with mostly
text, these paragraph gaps look unsightly.

Also, this method is incompatible with grid typesetting, where
all glue stretching must be quantised to the height of a line.

\subsection{\q{\lwc/}}

\Lwc/ has none of these issues: it eliminates the widows in a document
while keeping a flush bottom margin and constant paragraph spacing.

To do so, \lwc/ lengthened the second paragraph by one line. If you look
closely, you can see that this stretched the interword spaces. This
stretching is noticeable when typesetting in a narrow text block, but
is mostly imperceptible with larger widths.

\Lwc/ automatically finds the \q{best} paragraph to stretch, so the
increase in interword spaces should almost always be minimal.

\section[sec:install]{Installation}
Most up-to-date \TeX~Live and Mik\TeX{} systems should already have \lwc/ installed. However, a manual installation may occasionally be required.

\subsection{\TeX~Live}
Run \type{tlmgr install lua-widow-control} in a terminal, or install using the \q{\TeX~Live Manager} \acronym{GUI}.

\subsection{Mik\TeX}
Run \type{mpm --install=lua-widow-control} in a terminal, or install using the \q{Mik\TeX{} Maintenance} \acronym{GUI}.

\subsection{Manual}
Currently, \mkxl/ (\LuaMetaTeX{}) users must manually install the package. Most other users will be better served by using the \lwc/ supplied by \TeX~Live and Mik\TeX{}; however, all users may manually install the package if desired. The procedure should be fairly similar regardless of your \acronym{OS}, \TeX{}  distribution, or format.

\subsection{Steps}
\startitemize[N]
    \item Download \type{lua-widow-control.tds.zip} from \goto{\acronym{CTAN}}[url(ctan)], \goto{GitHub}[url(download)] or the \goto{\ConTeXt{}~Garden}[url(https://modules.contextgarden.net/cgi-bin/module.cgi/action=view/id=127)].
    \item Unzip the release into your \type{TEXMFLOCAL/} directory. (You can find its location by running \type{kpsewhich --var-value TEXMFHOME} in a terminal)
    \item Refresh the filename database: \startitemize[1]
        \item \ConTeXt: \type{mtxrun --generate}
        \item \TeX~Live: \type{mktexlsr}
        \item Mik\TeX: \type{initexmf --update-fndb}
    \stopitemize
\stopitemize

\section{Dependencies}
\Lwc/ does have a few dependencies; however, these will almost certainly be met by all but the most minimal of \TeX{} installations.

\subsection{Plain~\TeX{}}
\Lwc/ requires \LuaTeX{} ($\ge$ 0.85) and the most recent version of \sans{luatexbase} (2015/10/04). Any version of \TeX~Live $\ge$ 2016 will meet these requirements.

\subsection{\LaTeX{}}
\Lwc/ requires \LuaTeX{} ($\ge$ 0.85), \LaTeX{} ($\ge$ 2020/10/01), and \sans{microtype} (any version). Any version of \TeX~Live $\ge$ 2021 will meet these requirements.

\Lwc/ also supports a \q{legacy} mode for older \LaTeX{} kernels. This uses an older version of the \LaTeX{} code while still using the most recent Lua code. This mode requires \LuaTeX{} ($\ge$ 0.85), \LaTeX{} ($\ge$ 2015/01/01), \sans{microtype} (any version), and \sans{etoolbox} (any version). Any version of \TeX~Live $\ge$ 2016 will meet these requirements.

Please note that when running in legacy mode, you cannot use the key--value interface. This legacy interface is undocumented, but mostly the same as the \q{Plain~\TeX{}} interface.

\subsection{\ConTeXt{}}
\Lwc/ supports both \mkxl/ (\LuaMetaTeX{}) and \mkiv/ (\LuaTeX{}).

\subsection{\OpTeX{}}
\Lwc/ works with any version of \OpTeX{} and has no dependencies.


\section[sec:usage]{Loading the Package}

\startTABLE[setups=commandtable]
    \NC Plain~\TeX{}
    \NC\inlineTEX{\input  lua-widow-control}
    \NC\NR
    \NC \LaTeX{}
    \NC\inlineTEX{\usepackage{lua-widow-control}}
    \NC\NR
    \NC \ConTeXt{}
    \NC\inlineTEX{\usemodule[lua-widow-control]}
    \NC\NR
    \NC \OpTeX{}
    \NC\inlineTEX{\load[lua-widow-control]}
    \NC\NR
\stopTABLE

\section{Options}

\Lwc/ is automatically enabled with the default settings as soon as you load it. Most users should not need to configure \lwc/; however, the packages provides a few commands.

\subsection{Overview}

\LaTeX{} users can set the options either when loading the package (\inlineTEX{\usepackage[$\meta{options}$]{lua-widow-control}}) or at any point using \inlineTEX{\lwcsetup{$\meta{options}$}}.

\ConTeXt{} users should use the \inlineTEX{\setuplwc[$\meta{options}$]} command for setting options at any point.

Plain~\TeX{} and \OpTeX{} are a little different. Some options require you to set a register (i.e., \inlineTEX{\lwcemergencystretch = $\meta{dimension}$}), while others use macro arguments (i.e., \inlineTEX{\lwcnobreak{$\meta{option}$}}).

\subsection{Disabling}

You may want to disable \lwc/ for certain portions of your
document. You can do so with the following commands:

\startTABLE[setups=commandtable]
    \NC \plainop/
    \NC\inlineTEX{\lwcdisable}
    \NC\NR
    \NC \LaTeX{}
    \NC\inlineTEX{\lwcsetup{disable}}
    \NC\NR
    \NC \ConTeXt{}
    \NC\inlineTEX{\setuplwc[state = stop]}
    \NC\NR
\stopTABLE

This prevents \lwc/ from stretching any paragraphs that follow. If a page
has earlier paragraphs where \lwc/ was still enabled and a \woo/ is
detected, \lwc/ will still attempt to remove the \woo/.

\subsection{Enabling}

\Lwc/ is enabled as soon as the package is loaded. If you
have previously disabled it, you will need to re-enable it to save new paragraphs.

\startTABLE[setups=commandtable]
    \NC \plainop/
    \NC\inlineTEX{\lwcenable}
    \NC\NR
    \NC \LaTeX{}
    \NC\inlineTEX{\lwcsetup{enable}}
    \NC\NR
    \NC \ConTeXt{}
    \NC\inlineTEX{\setuplwc[state = start]}
    \NC\NR
\stopTABLE

\subsection{Automatically disabling}

You may want to disable \lwc/ for certain commands where
stretching is undesirable such as section headings. Of course, manually
disabling and
then enabling \lwc/ multiple times
throughout a document would quickly become tedious, so \lwc/ provides
some options to do this automatically for you.

\Lwc/ automatically patches the default \LaTeX{}, \ConTeXt{},
Plain~\TeX{}, \OpTeX{}, \sans{memoir}, \sans{\acronym{KOMA}-Script}, and
\sans{titlesec} section commands, so you don't need to patch these.
Any others, though, you'll need to patch yourself.

\startTABLE[setups=commandtable]
    \NC \plainop/
    \NC \inlineTEX{\lwcdisablecmd $\meta{\backslash macro}$}
    \NC\NR
    \NC \LaTeX{}
    \NC \inlineTEX{\lwcsetup{disablecmds = {$\meta{macronameone}$, $\meta{macronametwo}$}}}
    \NC\NR
    \NC \ConTeXt{}
    \NC \inlineTEX{\prependtoks\lwc$\hskip-0.5em\relax$@patch@pre\to\everybefore$\hskip-0.5em\relax\meta{hook}$}
    \NC\NR\NC\NC \inlineTEX{\prependtoks\lwc$\hskip-0.5em\relax$@patch@pre\to\everyafter$\hskip-0.5em\relax\meta{hook}$}
    \NC\NR
\stopTABLE

The Plain~\TeX{}, \OpTeX, and \ConTeXt commands \emph{append} to the list of patched commands: they simply patch the provided commands while leaving the original patches in place. The \LaTeX{} option \emph{sets} the list of patched commands: it replaces the default list with the provided list.

\subsection{\estretch/}

\Lwc/ defaults to an \estretch/ value of 3~em for stretched paragraphs,
but you can configure this.

\Lwc/ will only use the \estretch/ when it cannot lengthen a paragraph
in any other way, so it is fairly safe to set this to a large value.
\TeX{} accumulates badness when \estretch/ is
used, so it's pretty rare that a paragraph that
requires any \estretch/ will actually be used on the page.

\startTABLE[setups=commandtable]
    \NC \plainop/
    \NC\inlineTEX{\lwcemergencystretch = $\meta{dimension}$}
    \NC\NR
    \NC \LaTeX{}
    \NC\inlineTEX{\lwcsetup{emergencystretch = $\meta{dimension}$}}
    \NC\NR
    \NC \ConTeXt{}
    \NC\inlineTEX{\setuplwc[emergencystretch = $\meta{dimension}$]}
    \NC\NR
\stopTABLE

\subsection{Penalties}

You can also manually adjust the penalties that \TeX{} assigns to \waos/.
Usually, the defaults are fine, but there are a few circumstances where you
may want to change them.

\startTABLE[setups=commandtable]
    \NC \plainop/
    \NC\inlineTEX{\widowpenalty = $\meta{integer}$}
    \NC\NR\NC\NC\inlineTEX{\clubpenalty = $\meta{integer}$}
    \NC\NR\NC\NC\inlineTEX{\brokenpenalty = $\meta{integer}$}
    \NC\NR
    \NC \LaTeX{}
    \NC\inlineTEX{\lwcsetup{widowpenalty = $\meta{integer}$}}
    \NC\NR\NC\NC\inlineTEX{\lwcsetup{orphanpenalty = $\meta{integer}$}}
    \NC\NR\NC\NC\inlineTEX{\lwcsetup{brokenpenalty = $\meta{integer}$}}
    \NC\NR
    \NC \ConTeXt{}
    \NC\inlineTEX{\setuplwc[widowpenalty = $\meta{integer}$]}
    \NC\NR\NC\NC\inlineTEX{\setuplwc[orphanpenalty = $\meta{integer}$]}
    \NC\NR\NC\NC\inlineTEX{\setuplwc[brokenpenalty = $\meta{integer}$]}
    \NC\NR
\stopTABLE

The value of these penalties determines how much \TeX{} should attempt
to stretch glue before passing the \woo/ to \lwc/. If you set the values to~1
(default), \TeX{} will stretch nothing and immediately trigger \lwc/;
if you set the values to 10\,000, \TeX{} will stretch infinitely and
\lwc/ will never be triggered. If you set the value to some intermediate
number, \TeX{} will first attempt to stretch some glue to remove the \woo/;
only if it fails will \lwc/ come in and lengthen a paragraph. As a special
case, if you set the values to~0, both \TeX{} and \lwc/ will completely
ignore the \woo/.

\subsection{\tex{nobreak} Behaviour}

When \lwc/ encounters an orphan, it removes it by moving the orphaned
line to the next page. The majority of the time, this is an appropriate
solution. However, if the orphan is immediately preceded by a section
heading (or \tex{nobreak}\slash\tex{penalty 10000}), \lwc/ would na\"ively separate a section heading from
the paragraph that follows. This is almost always undesirable, so \lwc/
provides some options to configure this.

\startTABLE[setups=commandtable]
    \NC \plainop/
    \NC\inlineTEX{\lwcnobreak{$\meta{value}$}}
    \NC\NR
    \NC \LaTeX{}
    \NC\inlineTEX{\lwcsetup{nobreak = $\meta{value}$}}
    \NC\NR
    \NC \ConTeXt{}
    \NC\inlineTEX{\setuplwc[nobreak = $\meta{value}$]}
    \NC\NR
\stopTABLE

The default value, \type{keep}, \emph{keep}s the section heading with
the orphan by moving both to the next page. The advantage to this option
is that it removes the orphan and retains any \tex{nobreak}s; the
disadvantage is that moving the section heading can create a large blank
space at the end of the page.

The value \type{split} \emph{split}s up the section heading and the
orphan by moving the orphan to the next page while leaving the heading
behind. This is usually a bad idea, but exists for the sake of
flexibility.

The value \type{warn} causes \lwc/ to give up on the page and do nothing,
leaving an orphaned line. \Lwc/ \emph{warn}s the user so that they can
manually remove the orphan.

\startplacefigure[location={here, top, bottom}, title={A visual comparison of the various \type{nobreak} options, where each box represents a different page.}, reference=tab:nobreak]
    \getbuffer[nobreak]
\stopplacefigure

\subsection{Maximum Cost}

\Lwc/ ranks each paragraph on the page by how much it would \q{cost} to
lengthen that paragraph. By default, \lwc/ selects the paragraph on
the page with the lowest cost; however, you can configure it to only
select paragraphs below a selected cost.

If there aren't any paragraphs below the set threshold, then \lwc/ won't
remove the \woo/ and will instead issue a warning.

\startTABLE[setups=commandtable]
    \NC \plainop/
    \NC\inlineTEX{\lwcmaxcost = $\meta{integer}$}
    \NC\NR
    \NC \LaTeX{}
    \NC\inlineTEX{\lwcsetup{max-cost = $\meta{integer}$}}
    \NC\NR
    \NC \ConTeXt{}
    \NC\inlineTEX{\setuplwc[maxcost = $\meta{integer}$]}
    \NC\NR
\stopTABLE

Based on my testing, \type{max-cost} values less than 1\,000
cause completely imperceptible changes in interword spacing; values less
than 5\,000 are only noticeable if you are specifically trying to pick out the
expanded paragraph on the page; values less than 15\,000 are typically
acceptable; and larger values may become distracting. \Lwc/ defaults to an
infinite \type{max-cost}, although the \q{strict} and \q{balanced} modes
sets the values to~5\,000 and 10\,000 respectively.

\Lwc/ uses a \q{cost function} $C$ that is initially defined as \startformula
    C = \frac{d}{\sqrt{l}}
\stopformula where $d$ is the total demerits of the paragraph, and $l$ is the number of lines in the paragraph; however, advanced users may also set a custom cost function by redefining the \inlineLUA{lwc.paragraph_cost(demerits, lines)} function.

\subsection{Debug Mode}

\Lwc/ offers a \q{debug} mode that prints extra information in the log files. This may be helpful to understand how \lwc/ is processing paragraphs and pages. If you are reporting an issue with \lwc/ make sure to compile your document with debug mode enabled!

\startTABLE[setups=commandtable]
    \NC \plainop/
    \NC\inlineTEX{\lwcdebug 1}
    \NC\NR\NC\NC\inlineTEX{\lwcdebug 0}
    \NC\NR
    \NC \LaTeX{}
    \NC\inlineTEX{\lwcsetup{debug = true}}
    \NC\NR\NC\NC\inlineTEX{\lwcsetup{debug = false}}
    \NC\NR
    \NC \ConTeXt{}
    \NC\inlineTEX{\setuplwc[debug = start]}
    \NC\NR\NC\NC\inlineTEX{\setuplwc[debug = stop]}
    \NC\NR
\stopTABLE

\section{Presets}

As you can see, \lwc/ provides quite a few options. Luckily, there are a few
presets that you can use to set multiple options at once. These presets are
a good starting point for most documents, and you can always manually
override individual options.

Currently, these presets are \LaTeX{}-only.

\startTABLE[setups=commandtable]
    \NC \LaTeX{}
    \NC\inlineTEX{\lwcsetup{$\meta{preset}$}}\NC\NR
\stopTABLE

\subsection{\type{default}}

If you use \lwc/ without any options, it defaults to this preset. In default
mode, \lwc/ takes all possible measures to remove \waos/ and will not
attempt to stretch any vertical glue. This usually
removes~$\mathord{>}\,95\%$ of all
possible \waos/. The catch here is that this mode is quite aggressive, so
it often leaves behind some fairly \q{spacey} paragraphs.

This mode is good if you want to remove (nearly) all \waos/ from your
document, without fine-tuning the results.

\subsection{\type{strict}}

\Lwc/ also offers a strict mode. This greatly restricts \lwc/'s tolerance
and makes it so that it will only lengthen paragraphs where the change will
be imperceptible.

The caveat with strict mode is that---depending on the document---
\lwc/ will be able to remove less than a third of the \waos/.
For the \waos/ that can't be automatically removed, a warning will be
printed to your terminal and log file so that a human can manually fix the
situation.

This mode is good if you want the best possible typesetting and are willing
to do some manual editing.

\subsection{\type{balanced}}

Balanced mode sits somewhere between default mode and strict mode. This mode
first lets \TeX{} stretch a little glue to remove the \woo/; only if that
fails will it then trigger \lwc/. Even then, the maximum paragraph cost is
capped. Here, \lwc/ can usually remove 90\% of a document's
potential \waos/, and it does so while making a minimal visual impact.

This mode is recommended for most users who care about their document's
typography. This mode is not the default since it doesn't remove all
\waos/: it
still requires a little manual intervention.

% %
\startplacetable[location={here, top, bottom}, title={\Lwc/ options set by each mode.}, reference=tab:modes]
    \startTABLE[setups=booktabs, style=tt, loffset=0.5em]
        \NC {\rm Option} \NC default \NC balanced \NC strict \NC\NR
        \NC max-cost \NC $\infty$ \NC 10000 \NC 5000 \NC\NR
        \NC emergencystretch \NC 3em \NC 1em \NC 0pt \NC\NR
        \NC nobreak \NC keep \NC keep \NC warn \NC\NR
        \NC widowpenalty \NC 1 \NC 500 \NC 1 \NC\NR
        \NC orphanpenalty \NC 1 \NC 500 \NC 1 \NC\NR
        \NC brokenpenalty \NC 1 \NC 500 \NC 1 \NC\NR
    \stopTABLE
\stopplacetable

\section{Compatibility}

The \lwc/ implementation is almost entirely in Lua, with only a minimal
\TeX{} footprint. It
doesn't modify the output routine, inserts\slash floats, \tex{everypar}, and
it doesn't insert any whatsits. This means that it should be compatible with
nearly any \TeX{} package, class, and format. Most changes that \lwc/ makes
are not observable on the \TeX{} side.

However, on the Lua side, \lwc/ modifies much of a page's internal
structure.
This should not affect any \TeX{} code; however, it may surprise
Lua code that modifies or depends on the page's low-level structure. This
does not matter for Plain~\TeX{} or \LaTeX{}, where even most Lua-based
packages don't depend on the node list structure; nevertheless, there are
a few issues with \ConTeXt{}.

Simple \ConTeXt{} documents tend to be fine, but many advanced
\ConTeXt{} features rely heavily on Lua and can thus be disturbed by
\lwc/. This is not a huge issue---the \lwc/ manual is
written in \ConTeXt{}---but \lwc/ is inevitably more reliable
with Plain \TeX{} and \LaTeX{} than with \ConTeXt{}.

Finally, keep in mind that adding \lwc/ to a document will almost certainly
change its page break locations.

\subsection{Columns}

Since \TeX{} and the formats implement column breaking and page
breaking through the
same internal mechanisms, \lwc/ removes \waos/ between columns just
as it does with \waos/ between pages.

\Lwc/ is known to work with the \LaTeX{} class option \type{twocolumn}
and the two-column output routine from Chapter~23 of \cite[texbook].

\subsection{Performance}

\Lwc/ runs entirely in a single pass, without depending on any
\type{.aux} files or the like. Thus, it shouldn't meaningfully
increase compile times. Although \lwc/ internally breaks each paragraph
twice, modern computers break paragraphs near-instantaneously, so you
are not likely to notice any slowdown.

\subsection{\eTeX{} penalties}

Knuth's original \TeX{} has three basic line penalties:
\tex{interlinepenalty}, which
is inserted between all lines; \tex{club\-penalty}, which is inserted after
the first line; and \tex{widow\-penalty}, which is inserted before the last
line. The \eTeX{} extensions generalize these commands with a
syntax similar to \tex{parshape}: with \tex{widow\-penalties} you can set the
penalty between the last, second last, and $n$th last lines of a paragraph;
\tex{inter\-line\-penalties} and \tex{club\-penalties} behave similarly.

\Lwc/ makes no explicit attempts to support these new -\type{penalties}
commands. Specifically, if you give a line a penalty that matches either
\tex{widowpenalty} or \tex{clubpenalty}, \lwc/ will treat the lines
exactly as it would a \woo/. So while these commands won't break \lwc/, they
are likely to lead to some unexpected behaviour.

\section{Stability}

The documented interfaces of \lwc/ can be considered stable: I'm not planning on removing or modifying any existing options or commands in any way that would break documents.

However, \lwc/'s page breaking \emph{is} subject to change. I will attempt to keep page breaks the same wherever reasonable; however, I will rarely make modifications to the algorithm when I can improve the output quality.

\section{Short last lines}

When lengthening a paragraph with \tex{looseness}, it is common advice to insert
ties (\type{~}) between the last few words of the paragraph to avoid
overly-short last lines\cite[texbook]. \Lwc/ does this automatically,
but instead of using ties or \tex{hbox}es, it uses the
\tex{par\allowbreak fill\allowbreak skip}
parameter. When lengthening a paragraph
(and only when lengthening a paragraph---remember, \lwc/ doesn't
interfere with \TeX{}'s output unless it detects a \woo/), \lwc/ sets
\tex{parfillskip} to \type{0pt plus 0.8\hsize}.
This normally makes the last line of a paragraph be at least
20\% of the overall paragraph's width, thus preventing
ultra-short~lines.

\section[sec:issues]{Known Issues}

\startitemize
    \item When a three-line paragraph is at the end of a page forming a
    widow, \lwc/ will remove the widow; however, it will leave an orphan.
    This issue is inherent to any process that removes widows through
    paragraph expansion and is thus unavoidable. Orphans are considered
    to be better than widows\cite[elements], so this is still an
    improvement.

    \item \Lwc/ only attempts to expand paragraphs; it never attempts to shrink them. See the \emph{TUGboat}~article\cite[article] §15.3 for further discussion. \githubissue{33}

    \item Sometimes a \woo/ cannot be eliminated because no paragraph has
    enough stretch. Sometimes this can be remediated by
    increasing \lwc/'s \estretch/; however, some pages just don't have
    any suitable paragraph.

    Long paragraphs with short words tend to be stretchier than short
    paragraphs with long words since these long paragraphs have more
    interword glue. Narrow columns also stretch more easily than wide columns
    since you need to expand a paragraph by less to make a new line.

    \item When running under \LuaMetaTeX{} (\ConTeXt{}), the log may
    contain many lines like \q{\type{luatex warning > tex: left parfill skip is gone}}. These messages
    are completely harmless (although admittedly quite annoying). \githubissue{7}

    \item \Lwc/ only attempts to expand paragraphs on a page with
    a \woo/. A global system like in \titlecite[global] would solve this;
    however, this is both \acronym{NP}-complete\cite[plass] and
    impossible to solve in a single pass. Very rarely would such a
    system remove widows or orphans that \lwc/ cannot.

    \item If there is a footnote on the last line of the page with a \woo/, \lwc/ will sometimes move the \q{footnote mark} but not the \q{footnote text}, thus breaking up a footnote. \githubissue{26}
\stopitemize

\section{Contributions}

If you have any issues with \lwc/, please create an issue at the \goto{project's GitHub page}[url(projecturl)]. Or, if you think that you can solve any of the \about[sec:issues] or add any new features, \goto{submit a \acronym{PR}}[url(projecturl)]. Thanks!

\section{License}

\Lwc/ is licensed under the \goto{\emph{Mozilla Public License}, version 2.0}[url(https://www.mozilla.org/en-US/MPL/2.0/)] or greater. The documentation is licensed under \goto{\acronym{CC-BY-SA}, version 4.0}[url(https://creativecommons.org/licenses/by-sa/4.0/legalcode)] or greater as well as the \acronym{MPL}.

Please note that a compiled document is \bold{not} considered to be an \q{Executable Form} as defined by the \acronym{MPL}. The \acronym{MPL} and \acronym{CC-BY-SA} licenses \bold{only} apply to you if you distribute the \lwc/ source code or documentation.

\section{References}

\placelistofpublications

\page
\setuplayout[
    width=middle,
    backspace=1in,
    height=9.25in,
]
\section[sec:implementation]{Implementation}

\usemodule[scite]
\setupbodyfont[10pt]
\setuphead[subsection][
    alternative=normal,
    style=\ssita,
    page=yes,
    continue=yes,
]

\subsection{lua-widow-control.lua}

\typeLUAfile{../source/lua-widow-control.lua}

\subsection{lua-widow-control.tex}

\typeTEXfile{../source/lua-widow-control.tex}

\subsection{lua-widow-control.sty}

\typeTEXfile{../source/lua-widow-control.sty}

\subsection{lua-widow-control-2022-02-22.sty}

\typeTEXfile{../source/lua-widow-control-2022-02-22.sty}

\subsection{t-lua-widow-control.mkxl}

\typeTEXfile{../source/t-lua-widow-control.mkxl}

\subsection{lua-widow-control.opm}

\typeTEXfile{../source/lua-widow-control.opm}

\subsection{Demo from \in{Table}[tab:demo]}

\typeTEXfile{\jobname-demo-text.tmp}

\stopdocument