gucci-on-fleek/lua-widow-control

Purpose and entry points

lua-widow-control is a LuaTeX package for Plain TeX, LaTeX, ConTeXt, and OpTeX. It automatically removes widows and orphans by making affected paragraphs longer, rather than stretching glue or reducing page/column length. User-facing loaders are format-specific wrappers: source/lua-widow-control.sty, source/t-lua-widow-control.mkxl, source/lua-widow-control.tex, and source/lua-widow-control.opm.

Core Lua engine

The format-independent implementation is source/lua-widow-control.lua. It runs inside the LuaTeX/LuaMetaTeX node-processing and line-breaking environment, examines pagination outcomes, and alters paragraph-breaking behavior when a page or column would leave an orphan or widow. The TeX wrappers provide the engine with macro-level integration points rather than duplicating the algorithm.

Format adaptation boundary

Each supported macro format has its own entry module and installation location:

• LaTeX: source/lua-widow-control.sty, including compatibility release source/lua-widow-control-2022-02-22.sty

• ConTeXt: source/t-lua-widow-control.mkxl

• Plain TeX: source/lua-widow-control.tex

• OpTeX: source/lua-widow-control.opm

These files isolate format conventions, option/interface syntax, and callback setup from the shared Lua logic.

Runtime and distribution

The required runtime is LuaTeX-family engines; tests explicitly cover LuaMetaTeX variants. The installable TDS tree mirrors source files into TeX search paths: texmf/tex/luatex/lua-widow-control/lua-widow-control.lua, texmf/tex/lualatex/lua-widow-control/lua-widow-control.sty, and texmf/tex/context/third/lua-widow-control/t-lua-widow-control.mkxl. The package is distributed through TeX Live/MiKTeX and external package channels referenced by the README (CTAN and ConTeXt Garden).

Build, documentation, and release artifacts

build.lua is the repository-level build entry point, producing package/distribution material. Source documentation includes the manual at docs/manual/lwc-manual.tex and background articles such as docs/articles/tb133chernoff-widows.ltx. Compiled deliverables are staged in the TDS doc tree, notably texmf/doc/luatex/lua-widow-control/lua-widow-control.pdf.

Verification flow

The test suite compiles fixture documents through format-specific suites, validating output behavior across LaTeX, ConTeXt, Plain TeX, and OpTeX: tests/latex/build.lua, tests/context/build.lua, and tests/plain/build.lua. Cases cover normal documents plus structural pressure points—columns, headings, footnotes, grids, floats, and draft modes—where pagination intervention is consequential. Shared test configuration and transformation support reside in tests/test-config.lua and tests/transform.xslt.

Primary flow

A document loads a format wrapper, which loads/configures the Lua engine. During typesetting, the engine observes paragraph/page or column breaking through LuaTeX facilities, detects potential widow/orphan layouts, and requests an alternate paragraph length/breaking result. The resulting node list returns to the host TeX engine for normal page construction and PDF output. The main boundary is therefore TeX macro setup → Lua node/line-break control → TeX pagination.