Add TUGboat article

.gitattributes

@@ -12,6 +12,6 @@ docs/** linguist-documentation
 licences/** linguist-documentation
 
 *.lvtext linguist-language=tex
-*.mkxl linguist-language=tex -linguist-documentation
+*.mkxl linguist-language=tex
 *.opm linguist-language=tex
 *.tltext linguist-generated linguist-language=text

.github/workflows/build-test-bundle.yml

@@ -54,10 +54,14 @@ jobs:
             context
             l3build
             blindtext
+            beebe
             kantlipsum
             linebreaker
             luatexbase
             optex
+            path
+            pgfplots
+            tugboat
 
       - name: Install ConTeXt LMTX
         run: |
@@ -82,13 +86,12 @@ jobs:
       - name: Build Documentation
         run: |
             cd "$GITHUB_WORKSPACE"
-            l3build doc "$lmtx_context"
+            l3build doc
 
       - name: Test the package
         run: |
             # Temporary workaround; see latex3/l3build#232
             sed -i '/TEXMFCNF/,+2d' "$(kpsewhich l3build-check.lua)"
-            export TEXMFHOME="$GITHUB_WORKSPACE/texmf"
 
             l3build check --show-log-on-error
 
@@ -101,7 +104,7 @@ jobs:
         if: "! ${{github.base_ref}}" # not a PR
         with:
           prerelease: true
-          artifacts: ./lua-widow-control.tds.zip, ./lua-widow-control.ctan.zip, ./texmf/doc/luatex/lua-widow-control/lua-widow-control.pdf
+          artifacts: ./lua-widow-control.tds.zip, ./lua-widow-control.ctan.zip, ./texmf/doc/luatex/lua-widow-control/lua-widow-control.pdf, ./texmf/doc/luatex/lua-widow-control/tb133chernoff-widows.pdf
           tag: release-${{github.sha}}
           commit: ${{github.sha}}
           name: Prerelease ${{github.sha}}

.gitignore

@@ -3,6 +3,8 @@
 # SPDX-License-Identifier: MPL-2.0+
 # SPDX-FileCopyrightText: 2022 Max Chernoff
 *.aux
+*.bbl
+*.blg
 *.log
 *.out
 *.pdf
@@ -14,3 +16,5 @@
 *.zip
 build/
 nogit-**
+tugboat.bib
+tugboat.def

CITATION.cff

@@ -0,0 +1,31 @@
+# lua-widow-control
+# https://github.com/gucci-on-fleek/lua-widow-control
+# SPDX-License-Identifier: MPL-2.0+
+# SPDX-FileCopyrightText: 2022 Max Chernoff
+
+cff-version: 1.2.0
+title: lua-widow-control
+authors:
+  - family-names: Chernoff
+    given-names: Max
+type: software
+repository-code: "https://github.com/gucci-on-fleek/lua-widow-control"
+license:
+ - MPL-2.0
+ - CC-BY-SA-4.0
+
+message: There is a TUGboat article available for this package.
+preferred-citation:
+  type: article
+  title: Automatically removing widows and orphans with lua-widow-control
+  authors:
+    - family-names: Chernoff
+      given-names: Max
+  doi: 10.47397/tb/43-1/tb133chernoff-widows
+  volume: 43
+  issue: 1
+  year: 2022
+  month: 5
+  start: 28
+  end: 39
+  journal: TUGboat

build.lua

@@ -8,7 +8,6 @@
 module = "lua-widow-control"
 
 local orig_targets = target_list
-local orig_options = option_list
 target_list = {}
 
 -- Tagging
@@ -75,26 +74,20 @@ end
 target_list.doc = {}
 target_list.doc.desc = "Builds the documentation"
 
--- option_list["lmtx-path"] = {
---     type = "string",
---     desc = "Path to the ConTeXt LMTX executable",
--- }
-
-function target_list.doc.func(args)
-    options["lmtx-path"] = args and args[1]
-    local context = options["lmtx-path"] or "context"
-
-    mkdir("./docs/tmp")
-    run("./docs",
-        os_setenv ..
-        " TEXMFHOME=" ..
-        abspath("./texmf") ..
-        os_concat ..
-        context ..
-        " lwc-documentation"
-    )
+function target_list.doc.func()
+    local context = os.getenv("lmtx_context") or "context"
+    local error = 0
 
-    return 0
+    mkdir("./docs/manual/tmp")
+    error = error + run("./docs/manual", context .. " lwc-manual")
+
+    error = error + run("./docs/TUGboat", context .. " tb133chernoff-widows-figure.ctx")
+    error = error + run("./docs/TUGboat", "lualatex tb133chernoff-widows.ltx")
+    error = error + run("./docs/TUGboat", "bibtex tb133chernoff-widows")
+    error = error + run("./docs/TUGboat", "lualatex tb133chernoff-widows.ltx")
+    error = error + run("./docs/TUGboat", "lualatex tb133chernoff-widows.ltx")
+
+    return error
 end
 
 -- Tests

docs/TUGboat/tb133chernoff-widows-figure.ctx

@@ -0,0 +1,166 @@
+% 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
+
+\startbuffer[demo-text]
+    \definepapersize[smallpaper][
+        width=6cm,
+        height=8.3cm
+    ]
+    \setuppapersize[smallpaper]
+
+    \def\lwc/{\sans{lua-\allowbreak widow-\allowbreak control}}
+    \def\Lwc/{\sans{lua-\allowbreak widow-\allowbreak control}}
+
+    \setupbodyfont[9pt]
+    \setupindenting[yes, 2em]
+    \setupalign[tolerant]
+
+    \definecolor[midlightgray][s=0.75]
+    \definepalet[layout][grid=midlightgray]
+    \showgrid[nonumber, none, lines]
+
+    \definefontfeature[default][default][expansion=quality,protrusion=quality]
+
+    \usetypescript[modern-base]
+    \setupbodyfont[reset,modern]
+
+    \setupalign[hz,hanging,tolerant]
+
+    \setuplanguage[en][spacing=packed]
+
+    \setuplayout[
+        topspace=0.1cm,
+        backspace=0.1cm,
+        width=middle,
+        height=\dimexpr 21\baselineskip + 1.1pt,
+        header=0pt,
+        footer=0pt,
+    ]
+
+    \starttext
+        \Lwc/ can remove most widows and orphans from a document, \emph{without}
+        stretching any glue or shortening any pages.
+
+        \ifx\uselooseness\undefined\else\uselooseness\fi It does so by automatically lengthening a paragraph on a page where a
+        widow or orphan would otherwise occur. While \TeX{} breaks paragraphs
+        into their natural length, \lwc/ is breaking the paragraph 1~line
+        longer than its natural length. \TeX{}'s paragraph is output to the
+        page, but \lwc/'s paragraph is just stored for later. When a widow or
+        orphan occurs, \lwc/ can take over. It selects the previously-saved
+        paragraph with the least badness; then, it replaces \TeX{}'s paragraph
+        with its saved paragraph. This increases the text block height of the
+        page by 1~line.
+
+        Now, the last line of the current page can be pushed to the top of the
+        next page. This removes the widow or the orphan without creating any
+        additional work.
+    \stoptext
+    \stoptext
+\stopbuffer
+\savebuffer[list=demo-text]
+
+\startbuffer[shorten]
+    \parskip=0pt
+    \input tb133chernoff-widows-figure-demo-text.tmp
+\stopbuffer
+
+\startbuffer[shorten-code]
+    \parskip=0pt
+    \clubpenalty=10000
+    \widowpenalty=10000
+\stopbuffer
+
+\startbuffer[stretch]
+    \parskip=0pt plus 1fill
+    \input tb133chernoff-widows-figure-demo-text.tmp
+\stopbuffer
+
+\startbuffer[stretch-code]
+    \parskip=0pt plus 1fill
+    \clubpenalty=10000
+    \widowpenalty=10000
+\stopbuffer
+
+\startbuffer[ignore]
+    \startsetups[*default]
+        \clubpenalty=0
+        \widowpenalty=0
+        \displaywidowpenalty=0
+        \interlinepenalty=0
+        \brokenpenalty=0
+    \stopsetups
+
+    \setups[*default]
+
+    \input tb133chernoff-widows-figure-demo-text.tmp
+\stopbuffer
+
+\startbuffer[ignore-code]
+    \parskip=0pt
+    \clubpenalty=0
+    \widowpenalty=0
+\stopbuffer
+
+\startbuffer[lwc]
+    \def\uselooseness{\looseness=1}
+    \input tb133chernoff-widows-figure-demo-text.tmp
+\stopbuffer
+
+% We're pretending that we're using LaTeX for the demo since that's what
+% 99% of users will be using.
+\startbuffer[lwc-code]
+    \usepackage{lua-widow-control}
+\stopbuffer
+
+\setupbodyfont[10pt]
+
+\setupbackend[format=PDF/A-1b:2005] % Force PDF version <1.5
+
+\startTEXpage[
+    align=normal,
+    width=39pc,
+    offset=0pt,
+]
+    \veryraggedcenter
+    \setupTABLE[row][1, 5][style=\bfa, align=middle, offset=0pt]
+    \setupTABLE[row][5][toffset=2ex]
+    \setupTABLE[frame=off, distance=5em]
+    \startTABLE
+        \NC Ignore
+        \NC Shorten
+        \NC\NR
+
+        \NC \typesetbuffer[ignore][frame=on, page=1, scale=925]
+        \NC \typesetbuffer[shorten][frame=on, page=1, scale=925]
+        \NC\NR
+
+        \NC \clip[height=1cm]{\typesetbuffer[ignore]
+                [frame=on, page=2, scale=925]}
+        \NC \clip[height=1cm]{\typesetbuffer[shorten]
+                [frame=on, page=2, scale=925]}
+        \NC\NR
+
+        \NC \typebuffer[ignore-code]
+        \NC \typebuffer[shorten-code]
+        \NC\NR
+
+        \NC Stretch
+        \NC \sans{lua-widow-control} \NC\NR
+
+        \NC \typesetbuffer[stretch][frame=on, page=1, scale=925]
+        \NC \typesetbuffer[lwc][frame=on, page=1, scale=925]
+        \NC\NR
+
+        \NC \clip[height=1cm]{\typesetbuffer[stretch]
+                [frame=on, page=2, scale=925]}
+        \NC \clip[height=1cm]{\typesetbuffer[lwc]
+                [frame=on, page=2, scale=925]}
+        \NC\NR
+
+        \NC \typebuffer[stretch-code]
+        \NC \typebuffer[lwc-code]
+        \NC\NR
+    \stopTABLE
+\stopTEXpage