Module typesetters.mixins.paragraphing
Paragraphing mixin for the typesetter.
Some code in this file comes from SILE's core typesetter.
License: MIT. Copyright (c) The SILE Organization / Simon Cozens et al.
This file is part of re·sil·ient, a set of extensions to SILE.
License: MIT. Copyright (c) 2025 Omikhkeia / Didier Willis
There is still some code smell in this component.
This component provides methods for line-breaking paragraphs, and assembling them into vertical boxes.
Class typesetter
| typesetter:boxUpNodes () | Box up the current node list into a list of vboxes. |
| typesetter:breakIntoLines (nodelist, breakWidth) | Break a list of nodes into lines. |
| typesetter:inhibitLeading () | Inhibit leading insertion before the next line. |
| typesetter:leadingFor (vbox, previous) | Compute the leading (interline space) between two lines. |
| typesetter:breakpointsToLines (breakpoints, nodelist) | Turn a list of breakpoints into a list of lines. |
| typesetter:_pruneDiscardables (slice) | Remove trailing and leading discardable nodes from a slice
The slice is modified in place. |
| typesetter:_addrlskip (slice, margins, hangLeft, hangRight) | Add left and right skips to a line slice. |
| typesetter:computeLineRatio (breakwidth, slice) | Compute the natural width and ratio for a line slice. |
Class typesetter
- typesetter:boxUpNodes ()
-
Box up the current node list into a list of vboxes.
SMELL: Bad name, undocumented behavior, ad-hoc logic... It does too many things at once, and should be refactored.
Empties self.state.nodes, breaks into lines, puts lines into vbox, adds vbox to Turns a node list into a list of vboxes
- typesetter:breakIntoLines (nodelist, breakWidth)
-
Break a list of nodes into lines.
CODE SMELL: Where we should have shaped the nodes is unclear. At least now we shouldn't shape them multiple times...
Parameters:
- nodelist table List of nodes to break into lines
- breakWidth SILE.types.length Target width for the lines
Returns:
-
table
List of lines
- typesetter:inhibitLeading ()
-
Inhibit leading insertion before the next line.
FIXME DUBIOUS NEED. And this is problematic in general baseline-grid layout.
- typesetter:leadingFor (vbox, previous)
-
Compute the leading (interline space) between two lines.
FIXME DUBIOUS APPROACH. Somewhat TeX-like in essence... But the grid package's hacks into it are dubious. This may have to be revisited if the page·ant page builder ever sees the light... In some future not yet written.
Parameters:
- vbox SILE.types.node.vbox Current line box
- previous SILE.types.node.vbox or nil Previous line box, if any
Returns:
-
SILE.types.node.vglue
Leading glue to insert
- typesetter:breakpointsToLines (breakpoints, nodelist)
-
Turn a list of breakpoints into a list of lines.
Parameters:
- breakpoints table Breakpoints as returned by the linebreaking algorithm
- nodelist table Corresponding list of nodes
Returns:
-
table
List of lines
- typesetter:_pruneDiscardables (slice)
-
Remove trailing and leading discardable nodes from a slice
The slice is modified in place.
For leading nodes, this means glues and penalties (i.e. all discardable nodes). For trailing nodes, this means glues (unless made non-discardable explicitly), zero boxes, and trailing kerns (if consecutive).
FIXME: Clearly messy logic here, needs a clarification pass.
Parameters:
- slice table Flat nodes from current line
- typesetter:_addrlskip (slice, margins, hangLeft, hangRight)
-
Add left and right skips to a line slice.
It takes taking into account the writing direction of the current frame, and potential hanging indents on either side.
(Breaking change) Compare to SILE's original typesetter:addrlskip() method, it doesn't do anything else than handling the margin skips.
Parameters:
- typesetter:computeLineRatio (breakwidth, slice)
-
Compute the natural width and ratio for a line slice.
The natural width is the width of the line if no stretching or shrinking were to occur. The ratio is the amount of stretch or shrink that would be needed to make the line fit exactly the break width.
SMELL: This should be a public method. But ptable.sile uses it, as the natural width of the line is not stored anywhere else. Bad design.
Parameters:
- breakwidth SILE.types.length Target width for the line
- slice table Line slice
Returns:
- number ratio Stretching (>0) or shrinking (<0) ratio
- SILE.types.length naturalTotals Natural width of the line