pskumaresh06/lua-widow-control

Purpose and Entry Points

lua-widow-control is a LuaTeX package for automatically eliminating widows and orphans in Plain TeX, LaTeX, ConTeXt, and OpTeX. Rather than changing page dimensions or glue, it adjusts paragraph line breaking so affected paragraphs occupy an additional line.

Format-specific user entry points load a shared Lua implementation:

• LaTeX: source/lua-widow-control.sty

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

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

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

Core Layout Engine

The package’s architectural center is source/lua-widow-control.lua. It operates inside the LuaTeX/LuaMetaTeX typesetting runtime, inspecting and manipulating the engine’s paragraph/page-building behavior to detect potential widow/orphan breaks and re-break the relevant paragraph longer. The Lua layer is format-agnostic; macro wrappers establish the integration contract and expose it to each macro package.

The legacy/compatibility LaTeX wrapper is retained at source/lua-widow-control-2022-02-22.sty.

Format Integration Boundary

Each macro frontend maps its host format’s loading and callback conventions to the shared engine:

• LaTeX package interface: source/lua-widow-control.sty

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

• ConTeXt module interfaces: source/t-lua-widow-control.mkxl, source/t-lua-widow-control.mkiv

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

This isolates format-specific macro syntax from Lua node-list and line-breaking logic. LuaTeX is the material execution dependency; tests also explicitly cover LuaMetaTeX variants.

Source-to-Distribution Packaging

source/ is the authoritative editable package source. texmf/ is the installable TDS-style distribution tree, mirroring runtime files by target format:

• shared Lua/Plain assets: texmf/tex/luatex/lua-widow-control/lua-widow-control.lua, texmf/tex/luatex/lua-widow-control/lua-widow-control.tex

• LaTeX assets: texmf/tex/lualatex/lua-widow-control/lua-widow-control.sty

• ConTeXt assets: texmf/tex/context/third/lua-widow-control/t-lua-widow-control.mkxl

• OpTeX asset: texmf/tex/optex/lua-widow-control/lua-widow-control.opm

build.lua is the top-level build/package orchestration entry point.

Validation Matrix

Regression testing is split by host macro package, reflecting the key integration boundary rather than merely unit-level behavior:

• LaTeX: tests/latex/build.lua, tests/latex/footnotes.tltext

• ConTeXt: tests/context/build.lua, tests/context/grid.tltext

• Plain TeX: tests/plain/build.lua, tests/plain/node-count.lvt

• OpTeX: tests/optex/build.lua, tests/optex/basic.tltext

Shared test settings and fixtures are in tests/test-config.lua and tests/common/basic.tex. Coverage includes ordinary paragraphs, columns, headings, footnotes, grids, draft modes, and LuaMetaTeX-specific expected output.

Documentation and Release Artifacts

Manual and article sources live under docs/, while compiled distributable documentation is installed under texmf/doc/luatex/lua-widow-control/. Key documentation sources are docs/manual/lwc-manual.tex and docs/articles/tb133chernoff-widows.ltx; their packaged PDFs include texmf/doc/luatex/lua-widow-control/lua-widow-control.pdf.

The package is distributed through TeX ecosystem channels (TeX Live, MiKTeX, CTAN, and ConTeXt Garden); no network service is required at runtime.