summaryrefslogtreecommitdiff
path: root/macros/luatex/generic/lua-widow-control/lwc-manual.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/luatex/generic/lua-widow-control/lwc-manual.tex')
-rw-r--r--macros/luatex/generic/lua-widow-control/lwc-manual.tex26
1 files changed, 21 insertions, 5 deletions
diff --git a/macros/luatex/generic/lua-widow-control/lwc-manual.tex b/macros/luatex/generic/lua-widow-control/lwc-manual.tex
index 7d68de6201..d2eb12c82e 100644
--- a/macros/luatex/generic/lua-widow-control/lwc-manual.tex
+++ b/macros/luatex/generic/lua-widow-control/lwc-manual.tex
@@ -37,12 +37,12 @@
\definetype[inlineTEX][option=tex, escape={$,$}, lines=hyphenated]
\definetype[inlineLUA][option=lua, escape={$,$}, lines=hyphenated]
-\input lwc-sample
+\input lwc-manual-samples
\startdocument[
title=lua-widow-control,
author=Max Chernoff,
- version=2.1.1, %%version
+ version=2.1.2, %%version
github=https://github.com/gucci-on-fleek/lua-widow-control,
ctan=https://www.ctan.org/pkg/lua-widow-control,
]
@@ -621,7 +621,7 @@ 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].
+and the two-column output routine from Chapter~23 of \titlecite[texbook].
\subsection{Performance}
@@ -648,11 +648,19 @@ commands. Specifically, if you give a line a penalty that matches either
exactly as it would a \woo/. So while these commands won't break \lwc/, they
are likely to lead to some unexpected behaviour.
+\subsection{Grids}
+
+\Lwc/ is fully compatible with the grid snapping features of \ConTeXt{} \mkiv/ and \mkxl/.
+
+\subsection{Footnotes}
+
+If there are footnotes (or any other type of inline \tex{insert}) present in the moved line, \lwc/ will move both the \q{footnote mark} and the \q{footnote text} such that both are on the same page. However, this may lead to an odd blank space at the bottom of the page since \lwc/ needs to move both the line and its footnotes. Footnotes cause the same page-breaking issues in unmodified Plain~\TeX{} and \LaTeX{}, so this is mostly unavoidable.
+
\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.
+However, \lwc/'s page breaking \emph{is} subject to change. I will attempt to keep page breaks the same whenever reasonable; however, I will \emph{rarely} make modifications to the algorithm when I can improve the output quality. Any such changes will be clearly noted in the release notes.
\section{Short last lines}
@@ -681,6 +689,8 @@ ultra-short~lines.
\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 \Lwc/ can only expand paragraphs that fit completely on a page. This is unavoidable due to the one-page-at-a-time model: you can't modify the bottom half of a paragraph since its top half has already shipped out, and you can't expand the top half of a paragraph since that can't remove orphans. This only causes issues if your document has paragraphs so long that a page only has two half-paragraphs and zero whole paragraphs.
+
\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
@@ -701,7 +711,7 @@ ultra-short~lines.
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}
+ \item \Lwc/ does not move footnotes in \mkxl/ due to limitations with the \LuaMetaTeX{} engine.
\stopitemize
\section{Contributions}
@@ -726,6 +736,12 @@ Please note that a compiled document is \bold{not} considered to be an \q{Execut
]
\section[sec:implementation]{Implementation}
+From here and until the end of this manual is the raw source code of \lwc/. This is primarily of interest to developers; most users need not read further.
+
+This code vaguely resembles the typical \LaTeX{} literate programming style, although I use extensive inline comments instead of arcane \sans{docstrip} macros. Hopefully this is useful as a reference for advanced \lwc/ users as well as anyone doing extensive node manipulation in \LuaTeX{}.
+
+If want to offer any improvements to the code below, please open an issue or a \acronym{PR} on \goto{GitHub}[url(projecturl)].
+
\usemodule[scite]
\setupbodyfont[10pt]
\setuphead[subsection][