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.tex159
1 files changed, 140 insertions, 19 deletions
diff --git a/macros/luatex/generic/lua-widow-control/lwc-manual.tex b/macros/luatex/generic/lua-widow-control/lwc-manual.tex
index 2b5be55196..ef46472225 100644
--- a/macros/luatex/generic/lua-widow-control/lwc-manual.tex
+++ b/macros/luatex/generic/lua-widow-control/lwc-manual.tex
@@ -28,7 +28,8 @@
\def\mkxl/{\ConTeXt~Mk\acronym{XL}}
\def\mkiv/{\ConTeXt~Mk\acronym{IV}}
\define\OpTeX{Op\kern-.05em\TeX}
-\def\LuaMetaTeX{LuaMeta\TeX}
+\def\LuaMeta{Lua\-Meta\-}
+\def\LuaMetaTeX{\LuaMeta\TeX}
\def\plainop/{Plain~\TeX{}/\OpTeX{}}
\let\q=\quotation
@@ -42,6 +43,7 @@
\definecolor[expanded][r=0.00, g=0.70, b=0.25]
\definecolor[failure] [r=0.90, g=0.00, b=0.25]
\definecolor[moved] [r=0.25, g=0.25, b=1.00]
+\definecolor[cost] [r=0.50, g=0.50, b=0.50]
\usemodule[markdown]
\define[4]\markdownRendererLinkPrototype{\goto{#1}[url(#3)]}
@@ -64,7 +66,7 @@
\startdocument[
title=lua-widow-control,
author=Max Chernoff,
- version=2.2.2, %%version
+ version=3.0.0, %%version
github=https://github.com/gucci-on-fleek/lua-widow-control,
ctan=https://www.ctan.org/pkg/lua-widow-control,
]
@@ -79,7 +81,7 @@ Ensure that your \TeX~Live/Mik\TeX{} distribution is up-to-date. Then, \LaTeX{}
\section{Preliminaries}
-This manual begins with a brief introduction to widows, orphans, and \lwc/. For an extended introduction and discussion of these topics, please see the \emph{TUGboat} article\cite[article] distributed with this manual (Links: \goto{local}[tb133chernoff-widows::], \goto{\acronym{CTAN}}[url(http://mirrors.ctan.org/macros/luatex/generic/lua-widow-control/tb133chernoff-widows.pdf)], \goto{GitHub}[url(https://github.com/gucci-on-fleek/lua-widow-control/releases/latest/download/tb133chernoff-widows.pdf)]). You can also skip ahead to the \goto{installation instructions on \at{page}[sec:install]}[sec:install] or the \goto{usage section starting at \at{page}[sec:usage]}[sec:usage].
+This manual begins with a brief introduction to widows, orphans, and \lwc/. For an extended introduction and discussion of these topics, please see the \emph{Zpravodaj} article\cite[zpravodaj] distributed with this manual (Links: \goto{local}[lwc-zpravodaj::], \goto{\acronym{CTAN}}[url(http://mirrors.ctan.org/macros/luatex/generic/lua-widow-control/lwc-zpravodaj.pdf)], \goto{GitHub}[url(https://github.com/gucci-on-fleek/lua-widow-control/releases/latest/download/lwc-zpravodaj.pdf)]). This same material is also available in two \emph{TUGboat} articles\cite[tugboat1, tugboat2] (Links: \goto{local}[tb133chernoff-widows::], \goto{\acronym{CTAN}}[url(http://mirrors.ctan.org/macros/luatex/generic/lua-widow-control/tb133chernoff-widows.pdf)], \goto{GitHub}[url(https://github.com/gucci-on-fleek/lua-widow-control/releases/latest/download/tb133chernoff-widows.pdf)]) if you prefer. You can also skip ahead to the \goto{installation instructions on \at{page}[sec:install]}[sec:install] or the \goto{usage section starting at \at{page}[sec:usage]}[sec:usage].
\section[sec:motivation]{Motivation}
@@ -295,6 +297,10 @@ Please note that when running in legacy mode, you cannot use the key--value inte
\subsection{\OpTeX{}}
\Lwc/ works with any version of \OpTeX{} and has no dependencies.
+\subsection{LuaMeta\TeX{}}
+
+\Lwc/ has preliminary support for LuaMeta\LaTeX{} and LuaMetaPlain. All features should work identically to the \LuaTeX{}-based version, although there are a few minor bugs. You should always make sure to use the latest engine, format, and \lwc/ since these formats are under rapid development.
+
\section[sec:usage]{Loading the Package}
@@ -449,6 +455,10 @@ only if it fails will \lwc/ come in and lengthen a paragraph. As a special
case, if you set the values to~0, both \TeX{} and \lwc/ will completely
ignore the \woo/.
+\Lwc/ will pick up on the values of \tex{widowpenalty}, \tex{clubpenalty}, and
+\tex{brokenpenalty} regardless of how you set them, so the use of these
+dedicated keys is entirely optional.
+
\subsection{\tex{nobreak} Behaviour}
When \lwc/ encounters an orphan, it removes it by moving the orphaned
@@ -521,11 +531,15 @@ sets the values to~5\,000 and 10\,000 respectively.
\Lwc/ uses a \q{cost function} $C$ that is initially defined as \startformula
C = \frac{d}{\sqrt{l}}
-\stopformula where $d$ is the total demerits of the paragraph, and $l$ is the number of lines in the paragraph; however, advanced users may also set a custom cost function by redefining the \inlineLUA{lwc.paragraph_cost(demerits, lines)} function.
+\stopformula where $d$ is the total demerits of the paragraph, and $l$ is the number of lines in the paragraph.
\subsection{Draft Mode}
-You can use the draft mode to visualize how \lwc/ processes pages. Any \color[failure]{remaining widows and orphans will be coloured red}, any \color[expanded]{expanded paragraphs will be coloured green}, and any \color[moved]{lines moved to the next page will be coloured blue}. In addition, the cost of each paragraph is shown in the right margin.
+\setuplwc[draft=start]
+\definecolor[lwc_expanded][s=0]
+\definecolor[lwc_failure][s=0]
+\definecolor[lwc_moved][s=0]
+You can use the draft mode to visualize how \lwc/ processes pages. Any \color[failure]{remaining widows and orphans will be coloured red}, any \color[expanded]{expanded paragraphs will be coloured green}, and any \color[moved]{lines moved to the next page will be coloured blue}. In addition, the \color[cost]{cost of each paragraph is shown in the right margin} as it is here.
\startTABLE[setups=commandtable]
\NC \plainop/
@@ -539,11 +553,63 @@ You can use the draft mode to visualize how \lwc/ processes pages. Any \color[fa
\NC\NR
\stopTABLE
-Advanced users may also customize the colours used by modifying the \inlineLUA{lwc.colours} table. The table keys are currently \type{expanded}, \type{failure}, and \type{moved}. The table values are \acronym{RGB} 3-tuples, where each element is a float between zero and one.
+Advanced users may also customize the colours used by modifying the \inlineLUA{lwc.colours} table. The table keys are currently \type{expanded}, \type{failure}, \type{moved}, and \type{cost}. The table values are \acronym{RGB} 3-tuples, where each element is a float between zero and one.
+
+You can also show or hide the costs and colours independently of each other.
+
+\startTABLE[setups=commandtable]
+ \NC \plainop/
+ \NC\inlineTEX{\lwcshowcosts 1}
+ \NC\NR\NC\NC\inlineTEX{\lwcshowcolours 1}
+ \NC\NR
+ \NC \LaTeX{}
+ \NC\inlineTEX{\lwcsetup{showcosts = true}}
+ \NC\NR\NC\NC\inlineTEX{\lwcsetup{showcolours = true}}
+ \NC\NR
+ \NC \ConTeXt{}
+ \NC\inlineTEX{\setuplwc[showcosts = start]}
+ \NC\NR\NC\NC\inlineTEX{\setuplwc[showcolours = start]}
+ \NC\NR
+\stopTABLE
+
+Plain~\TeX{} users will need to modify their output routines to be able to see the costs. Before you ship out the page, you should call \inlineTEX{\lwcpreshipout} with a box number as its argument. For example, here is some sample code to correctly reproduce the standard Plain~\TeX{} output routine:
+
+\startTEX
+\newbox\tempshipoutbox
+\output={
+ \setbox\tempshipoutbox=\vbox{
+ \makeheadline
+ \pagebody
+ \makefootline
+ }
+ \lwcpreshipout\the\tempshipoutbox
+ \shipout\box\tempshipoutbox
+ \advancepageno
+}
+\stopTEX
+
+Setting the output routine like this is automatic in all other formats. \Lwc/ does not modify the output routine in Plain~\TeX{} since most of its users likely have their own output routines.
+\subsection{Draft Offset}
+
+In draft mode, the paragraph costs are printed in the margins, offset a certain distance from the page edge. By default, this offset is set to \unit{1 inch}; however, you can change this to any value that you want:
+
+\startTABLE[setups=commandtable]
+ \NC \plainop/
+ \NC\inlineTEX{\lwcdraftoffset = $\meta{dimension}$}
+ \NC\NR
+ \NC \LaTeX{}
+ \NC\inlineTEX{\lwcsetup{draftoffset = $\meta{dimension}$}}
+ \NC\NR
+ \NC \ConTeXt{}
+ \NC\inlineTEX{\setuplwc[draftoffset = $\meta{dimension}$]}
+ \NC\NR
+\stopTABLE
+
+\setuplwc[draft=stop]
\subsection{Debug Mode}
-\Lwc/ offers a \q{debug} mode that prints extra information in the log files. This may be helpful to understand how \lwc/ is processing paragraphs and pages, although the information is likely inscrutable unless you are the package's author. If you are reporting an issue with \lwc/ make sure to compile your document with debug mode enabled!
+\Lwc/ offers a \q{debug} mode that prints extra information in the log files. This may be helpful to understand how \lwc/ is processing paragraphs and pages, although the information is likely inscrutable unless you are the package's author. If you are reporting an issue with \lwc/, make sure to compile your document with debug mode enabled!
\startTABLE[setups=commandtable]
\NC \plainop/
@@ -567,11 +633,13 @@ presets that you can use to set multiple options at once. These presets are
a good starting point for most documents, and you can always manually
override individual options.
-Currently, these presets are \LaTeX{}-only.
+Presets are available only with \LaTeX{} and \ConTeXt{}.
\startTABLE[setups=commandtable]
\NC \LaTeX{}
\NC\inlineTEX{\lwcsetup{$\meta{preset}$}}\NC\NR
+ \NC \ConTeXt{}
+ \NC\inlineTEX{\setuplwc[$\meta{preset}$]}\NC\NR
\stopTABLE
\subsection{\type{default}}
@@ -627,11 +695,51 @@ still requires a little manual intervention.
\stopTABLE
\stopplacetable
+\section{Lua Interface}
+
+\Lwc/ provides a few public functions and tables that you can safely use or modify as documented. Any Lua interfaces that aren't documented below are subject to change at any time, but ff you do want to use an undocumented interface, please let me know and can easily document it.
+
+\subsection{Costs}
+
+\Lwc/ uses a \q{cost function} to select which paragraph to expand. Typically, this depends on the number of lines and demerits in the broken paragraph; however, you can redefine this function to do something else if you want. The default function is defined as:
+
+\startLUA
+--- The "cost function" to use.
+---
+--- @param demerits number The demerits of the broken paragraph
+--- @param lines number The number of lines in the broken paragraph
+--- @param nat_demerits number The demerits of the naturally-broken paragraph
+--- @param nat_lines number The number of lines in the naturally-broken paragraph
+--- @param head node The head of the broken paragraph
+--- @return number cost The cost of the broken paragraph
+function lwc.paragraph_cost(demerits, lines, nat_demerits, nat_lines, head)
+ return demerits / math.sqrt(lines)
+end
+\stopLUA
+
+\subsection{Activation}
+
+Typically, \lwc/ determines if there are \waos/ at the end of a page by checking the \tex{outputpenalty} register. However, you can use a custom check if you want. The default check is defined as:
+
+\startLUA
+--- Determines if we should "activate" lwc for the current page/column.
+---
+--- @param penalty number The \outputpenalty for the current page/column
+--- @param paragraphs table<table<string, node|number>> The `paragraphs` table
+--- @param head node The head of the current page/column
+--- @return boolean activate True if lwc should move the last line on this page
+function lwc.should_remove_widows(penalty, paragraphs, head)
+ return is_matching_penalty(penalty)
+end
+\stopLUA
+
+By setting a custom activation and cost function, you can transform \lwc/ from a \wao/ remover into a custom layout customization tool.
+
\section{Compatibility}
The \lwc/ implementation is almost entirely in Lua, with only a minimal
\TeX{} footprint. It
-doesn't modify the output routine, inserts\slash floats, \tex{everypar}, and
+doesn't modify the output routine, \tex{everypar}, and
it doesn't insert any whatsits. This means that it should be compatible with
nearly any \TeX{} package, class, and format. Most changes that \lwc/ makes
are not observable on the \TeX{} side.
@@ -644,15 +752,32 @@ does not matter for Plain~\TeX{} or \LaTeX{}, where even most Lua-based
packages don't depend on the node list structure; nevertheless, there are
a few issues with \ConTeXt{}.
-Simple \ConTeXt{} documents tend to be fine, but many advanced
-\ConTeXt{} features rely heavily on Lua and can thus be disturbed by
-\lwc/. This is not a huge issue---the \lwc/ manual is
-written in \ConTeXt{}---but \lwc/ is inevitably more reliable
-with Plain \TeX{} and \LaTeX{} than with \ConTeXt{}.
+However, on the Lua side, \lwc/ modifies much of a page's internal
+structure. This should not affect any \TeX{} code; however, it may surprise
+Lua code that modifies or depends on the page's low-level structure. This
+does not affect Plain~\TeX{} or \LaTeX{} where even most Lua-based packages
+don't depend on the node list structure. \ConTeXt{} \emph{does} depend on
+this internal node structure; however, I have carefully tested the package
+to ensure that this causes no issues.
Finally, keep in mind that adding \lwc/ to a document will almost certainly
change its page break locations.
+\subsection{Formats}
+
+\Lwc/ runs on all known Lua\TeX{}-based formats: Plain~Lua\TeX{},
+Lua\LaTeX{}, \ConTeXt{} Mk\acronym{IV}, and~\OpTeX{}. Unless otherwise
+documented, all features should work equally well in all formats.
+
+\Lwc/ is also fully-compatible with the \LuaMeta\TeX{}-based formats:
+\ConTeXt{} Mk\acronym{XL}\slash\acronym{LMTX}, \LuaMeta\LaTeX{}, and
+\LuaMeta{}Plain. \ConTeXt{} Mk\acronym{XL} works equally
+well as \ConTeXt{} Mk\acronym{IV} and Lua\LaTeX{}; however, \LuaMeta\LaTeX{}
+and \LuaMeta{}Plain support is still quite early. All features should work,
+although there are still a few minor bugs.
+
+All told, \lwc/ supports 7 different format\slash{}engine combinations.
+
\subsection{Columns}
Since \TeX{} and the formats implement column breaking and page
@@ -712,7 +837,7 @@ but instead of using ties or \tex{hbox}es, it uses the
parameter. When lengthening a paragraph
(and only when lengthening a paragraph---remember, \lwc/ doesn't
interfere with \TeX{}'s output unless it detects a \woo/), \lwc/ sets
-\tex{parfillskip} to \type{0pt plus 0.8\hsize}.
+\tex{parfillskip} to \type{0.75\hsize plus 0.05\hsize minus 0.75\hsize}.
This normally makes the last line of a paragraph be at least
20\% of the overall paragraph's width, thus preventing
ultra-short~lines.
@@ -746,10 +871,6 @@ ultra-short~lines.
however, this is both \acronym{NP}-complete\cite[plass] and
impossible to solve in a single pass. Very rarely would such a
system remove widows or orphans that \lwc/ cannot.
-
- \item \Lwc/ does not move footnotes in \mkxl/ due to limitations with the \LuaMetaTeX{} engine. \githubissue{38}
-
- \item Draft mode does not colour any text in \mkxl/. Draft mode will not colour the first line of a page in \mkiv/ and \OpTeX{}. \githubissue{39}
\stopitemize
\section{Contributions}