summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/luatex
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2021-11-08 23:21:20 +0000
committerKarl Berry <karl@freefriends.org>2021-11-08 23:21:20 +0000
commite9ab0cf018b97d1ca34b3b78396d5152b19ac92c (patch)
treef23ba71514aa2ec5a8be60a0d3f3078a3e4d777a /Master/texmf-dist/source/luatex
parentd15021e33a9c5e367a54267fd7c0db9798c4ba90 (diff)
lua-widow-control (9nov21)
git-svn-id: svn://tug.org/texlive/trunk@61002 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/luatex')
-rw-r--r--Master/texmf-dist/source/luatex/lua-widow-control/lwc-documentation.bib2
-rw-r--r--Master/texmf-dist/source/luatex/lua-widow-control/lwc-documentation.mkxl66
-rw-r--r--Master/texmf-dist/source/luatex/lua-widow-control/lwc-documentation.tex114
-rw-r--r--Master/texmf-dist/source/luatex/lua-widow-control/lwc-sample.tex2
4 files changed, 120 insertions, 64 deletions
diff --git a/Master/texmf-dist/source/luatex/lua-widow-control/lwc-documentation.bib b/Master/texmf-dist/source/luatex/lua-widow-control/lwc-documentation.bib
index 4778435f1e4..009c0e5cfa5 100644
--- a/Master/texmf-dist/source/luatex/lua-widow-control/lwc-documentation.bib
+++ b/Master/texmf-dist/source/luatex/lua-widow-control/lwc-documentation.bib
@@ -1,7 +1,7 @@
% 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: 2021 gucci-on-fleek
+% SPDX-FileCopyrightText: 2021 Max Chernoff
@book{texbook,
author = {Donald E. Knuth},
diff --git a/Master/texmf-dist/source/luatex/lua-widow-control/lwc-documentation.mkxl b/Master/texmf-dist/source/luatex/lua-widow-control/lwc-documentation.mkxl
index f8208bcc4cf..a4d153de5b9 100644
--- a/Master/texmf-dist/source/luatex/lua-widow-control/lwc-documentation.mkxl
+++ b/Master/texmf-dist/source/luatex/lua-widow-control/lwc-documentation.mkxl
@@ -1,9 +1,10 @@
% lua-widow-control
% https://github.com/gucci-on-fleek/lua-widow-control
% SPDX-License-Identifier: MPL-2.0+
-% SPDX-FileCopyrightText: 2021 gucci-on-fleek
+% SPDX-FileCopyrightText: 2021 Max Chernoff
\startenvironment[lwc-documentation]
+\unprotect
\mainlanguage[en]
@@ -85,6 +86,8 @@ fonts.handlers.otf.addfeature {
%%%%%%%%%%%%%%%%%%%%%%
\setuppagenumbering[location=footer, style=\ss\lining]
+\let\old@tex=\tex
+\def\tex#1{\expandafter\old@tex\normalexpanded{{#1}}} % Allow expansion in the \tex macro (for \allowbreak)
% Acronym styling
\definecharacterkerning[acronymkerning][factor=0.05]
@@ -103,7 +106,7 @@ setbounds currentpicture to boundingbox OverlayBox;
\defineoverlay[warning][\useMPgraphic{warning}]
\define[1]\warning{
- \blank[big]
+ \blank[line]
\midaligned{\framed[
frame=off,
background=warning,
@@ -115,11 +118,17 @@ setbounds currentpicture to boundingbox OverlayBox;
#1
}}
- \blank[big]
+ \blank[line]
}
-\setupitemize[each][packed][style=\lining]
-\setupcaptions[headstyle=\ssbf\lining, style=\ss]
+\setupitemize[each][
+ style=\lining,
+ inbetween={\blank[quarterline]},
+]
+\setupcaptions[
+ headstyle=\ssbf\lining,
+ style=\ss,
+]
\setupdelimitedtext[blockquote][
style=\ss,
@@ -140,13 +149,13 @@ setbounds currentpicture to boundingbox OverlayBox;
\word
\bfb
\feature[+][smallcaps]
- \spaceskip=0.4em
+ \interwordspace=0.4em
\veryraggedcenter
\stopsetups
\setuphead[section][
- before={\setuplwc[state=stop]\blank[big, preference]},
- after={\blank[medium, samepage]\setuplwc[state=start]},
+ before={\blank[big, preference]},
+ after={\blank[medium, samepage]},
textstyle=\setups{style:section},
number=no,
]
@@ -190,8 +199,30 @@ setbounds currentpicture to boundingbox OverlayBox;
title={},
author={},
version={},
+ ctan={},
+ github={},
]
+\startluacode
+local function strip_url(str)
+ local url_table = url.hashed(str)
+ url_table.fragment = nil
+ url_table.scheme = nil
+ url_table.authority = url_table.authority:gsub("^www%.", "")
+ tex.sprint(-2, url.decode(url.construct(url_table)))
+end
+
+interfaces.implement {
+ name = "strip_url",
+ actions = strip_url,
+ arguments = "1 string"
+}
+\stopluacode
+
+\define[1]\strippedurl{%
+ \goto{\tt\hyphenatedurl{\clf_strip_url{#1}}}[url(#1)]
+}
+
\startsetups[titleblock]
\startalignment [middle]
\begingroup
@@ -204,6 +235,8 @@ setbounds currentpicture to boundingbox OverlayBox;
\begingroup
\ssa\lining
+ \documentvariable{author}
+ \blank[medium]
v\,\documentvariable{version}
\par
\endgroup
@@ -212,7 +245,8 @@ setbounds currentpicture to boundingbox OverlayBox;
\blackrule[depth=-0.25\baselineskip, height=\dimexpr0.25\baselineskip + 0.4pt, width=8em]
\par
- \from[projecturl]
+ \strippedurl{\documentvariable{ctan}}
+ \strippedurl{\documentvariable{github}}
\blank[big]
\noindentation
@@ -269,24 +303,16 @@ setbounds currentpicture to boundingbox OverlayBox;
\setupbtxlist[apa][
alternative=a,
before=,
- after=,
+ after={\blank[quarterline]},
style=\lining,
margin=0pt,
width=1.5em,
]
-\unprotect
\starttexdefinition mutable protected btx:apa:url
- \goto{
- \hyphenatedurl{
- \clf_btxflush{\currentbtxdataset}{\currentbtxtag}{url}
+ \strippedurl{\clf_btxflush{\currentbtxdataset}{\currentbtxtag}{url}
}
- }[
- url(
- \clf_btxflush{\currentbtxdataset}{\currentbtxtag}{url}
- )
- ]
\stoptexdefinition
-\protect
+\protect
\stopenvironment
diff --git a/Master/texmf-dist/source/luatex/lua-widow-control/lwc-documentation.tex b/Master/texmf-dist/source/luatex/lua-widow-control/lwc-documentation.tex
index adc8e119aa3..40923c3707a 100644
--- a/Master/texmf-dist/source/luatex/lua-widow-control/lwc-documentation.tex
+++ b/Master/texmf-dist/source/luatex/lua-widow-control/lwc-documentation.tex
@@ -3,7 +3,7 @@
% 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: 2021 gucci-on-fleek
+% SPDX-FileCopyrightText: 2021 Max Chernoff
% Warning: Compiles slowly
@@ -13,7 +13,8 @@
\usebtxdataset[lwc-documentation.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][][latest release]
+\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}}
@@ -28,42 +29,41 @@
\def\titlecite[#1]{\cite[title][#1]\cite[#1]}
\usemodule[vim]
-\definevimtyping[TEX][syntax=tex, lines=split, escape=comment]
-\definevimtyping[LUA][syntax=lua, lines=split, escape=comment]
+\definevimtyping[TEX][syntax=tex, lines=split, escape=comment, directory=tmp]
+\definevimtyping[LUA][syntax=lua, lines=split, escape=comment, directory=tmp]
\input lwc-sample
\startdocument[
title=lua-widow-control,
- author=gucci-on-fleek,
- version=1.0.0, %%version
+ author=Max Chernoff,
+ version=1.1.0, %%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{} 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. Instead, \lwc/ automatically lengthens a paragraph on a page where a \woo/ would otherwise occur.
-
-\section{Quick Start}
-Install \lwc/ by unzipping the \from[download] in your \type{TEXMFLOCAL} directory. Rebuild the filename database. Place \inlineTEX{\usepackage{lua-widow-control}} in the preamble of your document.
-
-For a more detailed explanation of the steps involved and a description of some of the finer points involved with using \lwc/, keep reading.
+\Lwc/ is a Plain~\TeX/\LaTeX/\ConTeXt{} 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.
\subject{Contents}
\placecontent[criterium=all]
+\page
-\warning{\Lwc/ works by modifying the internal structure of each page. In \bold{rare} scenarios, this could delete or duplicate paragraphs or lines when a page break is triggered. All known bugs have been fixed, but I would still caution against using \lwc/ in any document where a single missing line would be disastrous. \Lwc/ should be sufficiently stable to use in typical documents.}
+\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 your document. For more details, see the \goto{Installation and Usage sections}[sec:install].
\section{Motivation}
\TeX{} provides top-notch typesetting: even 40 years after its first release, no other program produces higher quality mathematical typesetting, and its paragraph-breaking algorithm is still state-of-the-art. However, its page breaking is not quite as sophisticated as its paragraph breaking and thus suffers from some minor issues.
-Unmodified \TeX{} typically has only 2 ways of dealing with \waos/: it can either shorten a page by 1 line, or it can stretch out some 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 behavior works quite well; however, for prose or any other document composed almost entirely of text, there is no vertical whitespace to stretch.
+Unmodified \TeX{} typically has only 2 ways of dealing with \waos/: it can either shorten a page by 1 line, or it can stretch out some 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 behavior works quite well; however, for prose or any other document composed almost entirely of text, there is no vertical whitespace to stretch.
-Since there were no ready-made and fully-automated solutions to remove \waos/ from prosaic documents, I decided to create \lwc/.
+Since there were no ready-made and fully-automated solutions to remove \waos/ from all types of documents, I decided to create \lwc/.
\section{Widows and Orphans}
\subsection{Widows}
-Widows occur when when the majority of a paragraph is on one page, but the last line is on the following page. Widows are undesirable for both aesthetics and readability. Aesthetically, it looks quite odd for a lone line to be at the start of the page. Functionally, the separation of a paragraph and its last line disconnects the two, causing the reader to lose context for the widowed line.
+Widows occur when when the majority of a paragraph is on one page or column, but the last line is on the following page or column. Widows are undesirable for both aesthetics and readability. Aesthetically, it looks quite odd for a lone line to be at the start of the page. Functionally, the separation of a paragraph and its last line disconnects the two, causing the reader to lose context for the widowed line.
\subsection{Orphans}
-Orphans are when the first line of a paragraph occurs on the page before the remainder of they paragraph. They are not nearly 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 do, so they tend to be ignored more often.
+Orphans are when the first line of a paragraph occurs on the page or column before the remainder of they paragraph. They are not nearly 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 do, so they tend to be ignored more often.
\startplacefigure[location={here, top, bottom}, title={A visual comparison of \waos/.}, reference=tab:widow]
\getbuffer[widow-orphan]
@@ -71,26 +71,26 @@ Orphans are when the first line of a paragraph occurs on the page before the rem
\section{\TeX's Pagination}
\subsection{Algorithm}
-It is tricky to understand how \lwc/ works if you aren't familiar with how \TeX{} breaks pages. Chapter~15 of \titlecite[texbook] (\q{How \TeX{} Makes
+It is tricky to understand how \lwc/ works if you aren't familiar with how \TeX{} breaks pages and columns. Chapter~15 of \titlecite[texbook] (\q{How \TeX{} Makes
Lines into Pages}) is the best reference for this; however, it goes into much more detail than most users require. As a supplemental resource, I can also recommend Section~27 of \titlecite[texbytopic], \goto{available online}[url(https://texdoc.org/serve/texbytopic/0#page=227)] for free. Below follows a \emph{very} simplified (and likely error-ridden) 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 vertical spaces.
However, some objects have penalties attached. These penalties make \TeX{} treat the object as if it is longer or shorter for the sake of page breaking. By default, \TeX{} assigns a penalties to the first and last lines of a paragraph (\waos/). This makes \TeX{} treat them as if they are larger or smaller than their actual size such that \TeX{} tends not to break them up.
-One important note: once \TeX{} begins breaking a page, it only breaking a page. That is, it will never go back and modify any content that has previously been added to its \emph{main vertical list}. That is, page breaking is a localized algorithm, without any backtracking.
+One important note: once \TeX{} begins breaking a page, it never goes back and modifies any content on the page. Page breaking is a localized algorithm, without any backtracking.
\subsection{Behavior}
Of course, this algorithm doesn't allow us to intuitively understand how \TeX{} deals with \waos/.
Due to the penalties attached to \waos/, \TeX{} treats them as if they are longer than they actually are. Widows and orphans with small penalties attached---like \LaTeX's default values of 150---are only treated as slightly taller than 1 line, while \waos/ with large penalties---values near 10\,000---are treated as if they are 2 lines tall. Because potential \wao/ lines are broken as if they are taller than they actually are, \TeX{} will tend to group them together on the same pages.
-However, when these lines are moved as a group, \TeX{} will have to make a page with less lines. \about[sec:demo] goes into further detail about how \TeX{} deals with these too-short pages. The main takeaway is that for a page exclusively filled with text, all of \TeX's builtin solutions come with compromises.
+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. The main takeaway is that for a page exclusively filled with text, all of \TeX's builtin solutions come with compromises.
-\section{Previous Work}
+\section{Other Solutions}
There have been a few previous attempts to improve upon \TeX's previously-discussed \wao/-handling abilities; however, none of these have been able to automatically remove \waos/ without stretching any glue or shortening any pages.
-\titlecite[tugboat-strategies] and \titlecite[tugboat-widows] both begin with comprehensive discussions of the methods of preventing \waos/. They both agree that \waos/ are bad and ought to be avoided; however, they each differ in solutions. \italic{Strategies}\cite[tugboat-strategies] proposes an output routine that reduces the length of facing pages by 1 line if necessary to remove \waos/ while \italic{Managing}\cite[tugboat-widows] proposes that the author manually rewrites or adjusts the \tex{looseness} when needed.
+\titlecite[tugboat-strategies] and \titlecite[tugboat-widows] both begin with comprehensive discussions of the methods of preventing \waos/. They both agree that \waos/ are bad and ought to be avoided; however, they each differ in solutions. \italic{Strategies}\cite[tugboat-strategies] proposes an output routine that reduces the length of facing pages by 1~line when necessary to remove \waos/ while \italic{Managing}\cite[tugboat-widows] proposes that the author manually rewrites or adjusts the \tex{looseness} when needed.
\titlecite[widow-assist] contains a file \type{widow-assist.lua} that automatically detects which paragraphs can be safely shortened or lengthened by 1 line. \titlecite[widows-and-orphans] alerts the author to the pages that contain widows or orphans. Combined, these packages make it very simple for the author to quickly remove \waos/ by adjusting the \tex{looseness} values; however, it still requires the author to make manual source changes after each revision.
@@ -149,7 +149,7 @@ This page also has no widows and it has a flushed bottom margin. However, the sp
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 behavior. However, in a page with mostly text, these paragraph gaps can look unsightly.
-In addition, this method is incompatible with typesetting on a grid since all glue stretch is quantized to the height of a line.
+In addition, this method is incompatible with typesetting on a grid since all glue stretch must be quantized to the height of a line.
\subsection{\lwc/}
\Lwc/ has none of these issues: it eliminates the widows in a document while keeping a flushed bottom margin and constant paragraph spacing.
@@ -158,28 +158,42 @@ To do so, \lwc/ lengthened the second paragraph by one line. If you look closely
\Lwc/ automatically finds the \q{best} paragraph to stretch, so the increase in interword spaces should almost always be minimal.
-\section{Installation}
+\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}
-Mik\TeX{} should automatically install the package when you include it in your document.
+Run \type{mpm --install=lua-widow-control} in a terminal, or install using the \q{Mik\TeX{} Maintenance} \acronym{GUI}.
\subsection{Manual}
-Currently, \ConTeXt{} \acronym{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.
+Currently, \ConTeXt{} \acronym{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 the \from[download] on GitHub.
+ \item Download \type{lua-widow-control.tds.zip} from \goto{\acronym{CTAN}}[url(ctan)] or \goto{GitHub}[url(download)].
\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 \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$ 2015/01/01), \sans{microtype} (any version), and \sans{etoolbox} (any version). Any version of \TeX~Live $\ge$ 2016 will meet these requirements.
+
+\subsection{\ConTeXt{}}
+\Lwc/ requires \ConTeXt{} \acronym{MKXL} (\LuaMetaTeX{}).
+
+
\section{Loading the Package}
\subsection{Plain \TeX}
@@ -194,6 +208,10 @@ Currently, \ConTeXt{} \acronym{MKXL} (\LuaMetaTeX{}) users must manually install
\inlineTEX{\usemodule[lua-widow-control]}
+\section{Columns}
+
+Since \TeX{} implements column breaking and page breaking through the same internal mechanisms, \lwc/ should remove \waos/ between columns just as well as it does with \waos/ between pages. This has been tested with the standard \LaTeX{} class option \type{twocolumn} and the two-column output routine from Chapter~23 of \cite[title][texbook].\cite[texbook] \Lwc/ should presumably work with any other multi-column implementation; however, due to the diversity and complexity of output~routines, this cannot be guaranteed.
+
\section{Advanced Usage}
\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 does provide a few commands.
@@ -204,7 +222,8 @@ Currently, \ConTeXt{} \acronym{MKXL} (\LuaMetaTeX{}) users must manually install
\startTABLE
\NC Enable (default) \NC \inlineTEX{\lwcenable} \NC\NR
\NC Disable \NC \inlineTEX{\lwcdisable} \NC\NR
-\NC \estretch/ \NC \inlineTEX{\lwcemergencystretch = 3em} \NC\NR
+\NC \estretch/ \NC \inlineTEX{\lwcemergencystretch=3em} \NC\NR
+\NC Selectively Disable \NC \inlineTEX{\lwcdisablecmd{\cmd}} \NC\NR
\stopTABLE
\subsection{\LaTeX{}}
@@ -212,6 +231,7 @@ Currently, \ConTeXt{} \acronym{MKXL} (\LuaMetaTeX{}) users must manually install
\NC Enable (default) \NC \inlineTEX{\lwcenable} \NC\NR
\NC Disable \NC \inlineTEX{\lwcdisable} \NC\NR
\NC \estretch/ \NC \inlineTEX{\setlength{\lwcemergencystretch}{3em}} \NC\NR
+\NC Selectively Disable \NC \inlineTEX{\lwcdisablecmd{\cmd}} \NC\NR
\stopTABLE
\subsection{\ConTeXt{}}
@@ -219,6 +239,8 @@ Currently, \ConTeXt{} \acronym{MKXL} (\LuaMetaTeX{}) users must manually install
\NC Enable (default) \NC \inlineTEX{\setuplwc[state = start]} \NC\NR
\NC Disable \NC \inlineTEX{\setuplwc[state = stop]} \NC\NR
\NC \estretch/ \NC \inlineTEX{\setuplwc[emergencystretch = 3em]} \NC\NR
+\NC Selectively Disable \NC \inlineTEX{\prependtoks\lwc@patch@pre \to\everybeforefoo} \NC\NR
+\NC \NC \inlineTEX{\prependtoks\lwc@patch@post\to\everyafterfoo} \NC\NR
\stopTABLE
\subsection{\estretch/}
@@ -227,19 +249,27 @@ You can configure the \estretch/ used when stretching a paragraph. The default v
\Lwc/ will only use 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{} still accumulates badness when \estretch/ is used, so its pretty rare that a paragraph that requires any \estretch/ will actually be used on the page.
-\section{Known Issues}
+\subsection{Selectively Disabling}
+Sometimes, you may want to disable \lwc/ for certain commands where stretching is undesirable. For example, you typically wouldn't want section headings to be stretched.
+
+You could just disable then reenable \lwc/ every time that you use the command; however, \lwc/ provides a convenience macro that will do this automatically for you. Place \inlineTEX{\lwcdisablecmd{\cmd}} in the preamble, and \lwc/ will not expand any arguments of \tex{cmd} in the document.
+
+\Lwc/ automatically patches the default \LaTeX{}, \ConTeXt{}, and Plain~\TeX{} section commands, so you shouldn't need to patch these yourself; however, \lwc/ does \bold{not} patch the non-standard section commands provided by \sans{memoir}, \sans{\acronym{KOMA}-script}, \sans{titlesec}, and others. You'll need to patch these yourself.
+
+Under \ConTeXt{}, you need to use a different method to selectively disable \lwc/. Instead of using \tex{lwcdisablecmd}, you should use one of the preexisting \tex{everyfoo} hooks as shown in the table above since patching commands is rarely advisable in \ConTeXt{}
+\section[sec:issues]{Known Issues}
\startitemize
- \item \Lwc/ will rarely fail to correctly move the last line on an expanded page to the next page in documents with \emph{very} small paper sizes. This tends to only occur with paper narrower than $\approx\unit{8 cm}$ or shorter than $\approx\unit{10 cm}$ and should not affect any typical documents.
+ \item \Lwc/ will not expand the first paragraph of a document.
- \item In multicolumn layouts, \lwc/ will remove \waos/ that occur between pages, but it will not remove \waos/ between columns. To do so would likely require modifying the output routine which would be a very difficult task.
+ \item \Lwc/ will rarely fail to correctly move the last line on an expanded page to the next page in documents with \emph{very} small paper sizes.
\item When a 3-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 better than widows, so this is still an improvement.
- \item Sometimes a \woo/ just cannot be eliminated because no paragraph has enough \q{stretch}. This can \emph{sometimes} be remediated by increasing \lwc/'s \estretch/; however, some pages just don't have enough \q{stretchy} paragraphs. Long paragraphs with short words tend to be \q{stretchier} than short paragraphs with long words since these long paragraphs will have more interword glue. Narrow columns also stretch easier than wide columns since you need to expand a paragraph by less to make a new line.
+ \item Sometimes a \woo/ cannot be eliminated because no paragraph has enough \q{stretch}. This can \emph{sometimes} be remediated by increasing \lwc/'s \estretch/; however, some pages just don't have enough \q{stretchy} paragraphs. Long paragraphs with short words tend to be \q{stretchier} than short paragraphs with long words since these long paragraphs will have more interword glue. Narrow columns also stretch easier than wide columns since you need to expand a paragraph by less to make a new line.
\item When running under \LuaMetaTeX, the log may be filled with lines like \q{\tt luatex warning > tex: left parfill skip is gone}. This is harmless and can be ignored. % I have no idea how to fix this. The LMTX manual has "\parfillleftskip" in the indices, but that's all that I can find about it.
- \item \Lwc/ will not expand the first paragraph of a document. This should never be an issue in any real-world documents.
+ \item \Lwc/ will rarely raise a \q{\tt Circular node list detected!} warning. This occurs when the replacement paragraph node list loops back on itself. Since there is no \q{end} to the paragraph, \lwc/ cannot splice the paragraph into the page. The only reasonable option in this scenario is to stop processing the page, without removing the \woo/.
\stopitemize
\section{The Algorithm}
@@ -248,29 +278,29 @@ You can configure the \estretch/ used when stretching a paragraph. The default v
\subsection{Paragraph Breaking}
First, \lwc/ hooks into the paragraph breaking process.
-Before a paragraph is broken by \TeX{}, \lwc/ grabs the unbroken paragraph. \Lwc/ then breaks the paragraph 1~line longer than its natural length and stores it for later.
-
-\Lwc/ does not interfere with how \TeX{} breaks paragraphs into their natural length.
+Before a paragraph is broken by \TeX{}, \lwc/ grabs the unbroken paragraph. \Lwc/ then breaks the paragraph 1~line longer than its natural length and stores it for later, \emph{without} interfering with how \TeX{} breaks paragraphs into their natural length.
After \TeX{} has broken its paragraph into its natural length, \lwc/ appears once again. Before the broken paragraph is added to the main vertical list, \lwc/ tags the first and last nodes of the paragraph. These tags create a relationship between the previously-saved lengthened paragraph and the start/end of the naturally-typeset paragraph on the page.
\subsection{Page Breaking}
-\Lwc/ intercepts \tex{box255} after the output routine and before it is shipped out.
+\Lwc/ intercepts \tex{box255} immediately before the output routine.
-First, \lwc/ analyzes the \openalty/ of the page. If the page was broken at a \woo/, the \openalty/ will have been set to the respective values of \tex{widow\allowbreak penalty} and \tex{orphan\allowbreak penalty}. If the \openalty/ is not indicative of a \woo/, \lwc/ will abort and return \tex{box255} unmodified.
+First, \lwc/ analyzes the \openalty/ of the page or column. If the page was broken at a \woo/, the \openalty/ will equal either \tex{widow\allowbreak penalty} or \tex{orphan\allowbreak penalty}. If the \openalty/ is not indicative of a \woo/, \lwc/ will stop and return \tex{box255} unmodified.
-At this point, we know that we have a \woo/ on the page, so we know that we need to lengthen the page by 1~line. We can iterate through the list of saved paragraphs to find the lengthened paragraph with the least demerits. Once we've selected a paragraph to replace, we can now traverse through the page to find the original version of this paragraph so that we can splice in the lengthened paragraph.
+At this point, we know that we have a \woo/ on the page, so we must lengthen the page by 1~line. We iterate through the list of saved paragraphs to find the lengthened paragraph with the least demerits. Once we've selected a paragraph to replace, we can now traverse through the page to find the original version of this paragraph that \TeX{} originally typeset. Once we find the original paragraph, we \q{splice} the lengthened paragraph in the place of the original.
-Finally, we pull the last line off of the page and then we place it onto the top of the \emph{recent contributions} list. Now, we can ship out the new, widow-free page.
+Since the page is now 1~line longer than it was before, we pull the last line off of the page to bring it back to its original length. We place the line onto the top of the \emph{recent contributions} list so that it is added to the start of the next page. Now, we can return the new, widow-free page to the output routine.
\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 are willing to help with any improvements, \goto{submit a \acronym{PR}}[url(projecturl)].
+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
diff --git a/Master/texmf-dist/source/luatex/lua-widow-control/lwc-sample.tex b/Master/texmf-dist/source/luatex/lua-widow-control/lwc-sample.tex
index eb844301cd5..787b91e8dc5 100644
--- a/Master/texmf-dist/source/luatex/lua-widow-control/lwc-sample.tex
+++ b/Master/texmf-dist/source/luatex/lua-widow-control/lwc-sample.tex
@@ -1,7 +1,7 @@
% 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: 2021 gucci-on-fleek
+% SPDX-FileCopyrightText: 2021 Max Chernoff
\startbuffer[demo-text]
\definepapersize[smallpaper][