Repository navigation
Expand file tree
/
Copy pathmarginalreader-linenums.lua
More file actions
690 lines (652 loc) · 33.5 KB
/
Copy pathmarginalreader-linenums.lua
File metadata and controls
690 lines (652 loc) · 33.5 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
-- marginalreader-linenums.lua
-- Line numbering for the marginalreader class.
-- Counts body text lines and stamps every Nth one with a number in the
-- inner margin, via a `post_linebreak_filter` callback.
--
-- Copyright (C) 2026 Dino Sepúlveda
--
-- This work may be distributed and/or modified under the conditions
-- of the LaTeX Project Public License, either version 1.3c of this
-- license or (at your option) any later version; see
-- https://www.latex-project.org/lppl.txt. This work has the LPPL
-- maintenance status `maintained'; the Current Maintainer is
-- Dino Sepúlveda. It is part of the marginalreader class -- see
-- marginalreader.cls for the full file list.
--
-- Departure from the design draft (the original design draft)
-- -------------------------------------------
-- The design draft's own Step 3 draft renders numbers with a hand-built
-- `pdf_literal` whatsit (`/F1 7 Tf ... Tj`), bypassing TeX's font system
-- entirely. That is fragile in exactly the way the design draft's own Step 6
-- warns about: `/F1` is simply assumed to be the PDF resource name of
-- *some* embedded font, with no actual guarantee that name maps to
-- anything sensible (or exists at all) in this document's resource
-- dictionary -- whatever the PDF viewer does with an unknown/wrong font
-- reference is undefined. That approach was NOT carried over.
--
-- What this module does instead: build real `glyph` nodes for each digit
-- directly with `node.direct`, using the font selected by the user-facing
-- `\linenumfont` declaration (captured as a font id from the TeX side --
-- see `M.set_font`/marginalreader.cls's `\AtBeginDocument` block) and that
-- font's own character metrics (`font.fonts[id].characters[c]`). This goes
-- through the engine's normal font/PDF-embedding pipeline like any other
-- typeset text -- real, subsetted, selectable/searchable glyphs, correct
-- metrics -- with no assumption about PDF resource names at all. Digit
-- glyphs are chained and packed with `node.direct.hpack`, mirroring the
-- box-construction idiom `marginalreader-margin.lua`'s own
-- `M.process_page` already uses successfully for splicing pre-built
-- content into a node list (same zero-extent-wrapper-with-`shift`
-- trick, same `dir="TLT"` fix that module's header comment documents
-- discovering -- both re-used here for the same reason).
--
-- No inter-digit kerning is looked up (each digit's own natural advance
-- width is used as-is); acceptable for v0.1 since digit glyphs in
-- practice are not kerned against each other in any font this class
-- ships a preset for.
--
-- Filtering for "real" text lines
-- --------------------------------
-- `post_linebreak_filter` fires once per paragraph with that paragraph's
-- freshly-broken vlist as `head`. Two empirically-confirmed complications
-- (a standalone probe document, built from this class's own real
-- machinery, was used to check both before relying on either --
-- see the development notes):
--
-- 1. `\mr@marginitem`'s `\vadjust{\box\mr@marginadjbox}` placement
-- (used by `\gloss`, `marginblock`, `\marginnote`, ...) splices a
-- zero-width/height/depth `hlist` directly into the SAME vlist as
-- the text line it is attached to -- i.e. a paragraph containing a
-- `\gloss` call hands this callback a vlist with the margin note's
-- box sitting as a SIBLING of the real text line, not nested inside
-- it. Confirmed directly (probe dump of `tests/test-gloss.tex`-style
-- content): the real line has hlist subtype 1 ("line" -- the
-- subtype LuaTeX gives specifically to boxes produced BY line-
-- breaking); the spliced-in margin-note box has subtype 2 ("box" --
-- an explicit box, i.e. exactly what `\hbox`/`\vadjust` material
-- is). Filtering on `getsubtype(n) == 1` excludes margin-note boxes
-- correctly and precisely -- confirmed against `node.subtypes
-- ("hlist")` on this installation (1 = "line", 2 = "box").
--
-- 2. Independently of anything this task adds, compiling ANY document
-- with this class (confirmed against the unmodified, pre-existing
-- `tests/test-skeleton.tex`, no `\gloss`/margin content at all)
-- produces a handful of EXTRA `post_linebreak_filter` firings, for
-- hlist nodes that ARE subtype 1 ("line") but contain no glyphs at
-- all. The count is constant regardless of body content (always the
-- same number of extra firings for a 1-paragraph document as an
-- 8-paragraph one), so this is not mis-attributed real content --
-- some pre-existing, unrelated-to-this-task mechanism in this
-- class/KOMA-Script/the LaTeX kernel evidently does a burst of
-- internal typesetting-adjacent work around page-breaking activity.
-- (Plausibly the same general phenomenon `marginalreader-margin
-- .lua`'s own header comment already documents for
-- `pre_output_filter`: "can fire MORE THAN ONCE for the same page
-- near the very end of a document ... tied to \end{document}'s own
-- aux-writing/cleanup passes rather than a real page" -- not
-- confirmed to be the exact same cause, but the same class of
-- symptom, and mitigated here the same way that file mitigates its
-- own version of it: make the spurious firing harmless by
-- construction rather than by chasing down its origin.) Since these
-- carry no glyphs, requiring at least one `glyph` node in the line
-- (`line_has_glyph`, below) excludes them, and doubles as a
-- reasonable definition of "a real, visible text line" on its own
-- merits regardless of this mechanism's origin.
--
-- Initially (single-chapter test document) this looked confined to
-- document end, immediately after all real content -- a later,
-- multi-chapter test showed firings of this same shape ALSO
-- clustering around ordinary mid-document page breaks (a `\chapter`
-- forces one as part of its own startup). This mattered beyond
-- M.number_lines' own counting: see "Heading detection" below for
-- a second bug this same fact caused and how it was fixed.
--
-- Heading lines are excluded by a THIRD, independent mechanism (a Lua
-- flag, not a node attribute or the above two checks -- see "Heading
-- detection" below).
--
-- Heading detection
-- ------------------
-- The design draft's Step 4 draft tries to mark heading lines by calling
-- `node.direct.set_attribute` on `tex.nest[tex.nest.ptr].tail` from a
-- `\vadjust{pre}` planted inside `\chapterlinesformat`/
-- `\sectionlinesformat`. That cannot work as written: at the point a
-- `\vadjust{pre}` whatsit is contributed (mid-horizontal-mode, while the
-- heading's own paragraph is still being ACCUMULATED), the "line" hlist
-- nodes this module needs to mark do not exist yet -- they are only
-- created later, when `\par`/line-breaking finishes the heading's
-- paragraph. Setting an attribute on whatever node happens to be
-- "current" at `\vadjust{pre}` time does not attach anything to those
-- not-yet-existing lines.
--
-- This module instead uses a plain Lua flag (`M.next_is_heading`),
-- set by `M.mark_heading_next` and consumed by the next
-- `post_linebreak_filter` firing THAT ACTUALLY SEES A REAL LINE.
-- marginalreader.cls arranges for `M.mark_heading_next` to run from
-- KOMA-Script's own `\AddtoDoHook{heading/begingroup/<level>}` hook --
-- confirmed, by reading scrbook.cls directly, to fire strictly BEFORE
-- the heading's own paragraph-producing code runs
-- (`\ExecuteDoHook{heading/begingroup/#1}` precedes the
-- `#6{...\sectionlinesformat...\@@par}` call that actually typesets the
-- title, in every one of scrbook.cls's internal sectioning-command
-- implementations).
--
-- "the NEXT firing that actually sees a real line", not simply "the
-- next firing", matters: `\chapter` forces a page break as part of its
-- own startup sequence, and empirically (debug-instrumented probe,
-- the development notes) that page break can itself produce one or more of
-- the glyph-free "ghost" `post_linebreak_filter` firings described above
-- ("Filtering for real text lines", point 2) -- and, for a chapter that
-- is not the document's first, these can land AFTER
-- `heading/begingroup/chapter` has already set the flag but BEFORE the
-- chapter title's own paragraph runs. An earlier version of this module
-- consumed the flag unconditionally on the first firing seen while it
-- was set, ghost or not -- which silently miscounted every chapter
-- title from the SECOND chapter onward as an ordinary body line (the
-- ghost firing consumed/cleared the flag first, leaving it already false
-- by the time the real title paragraph ran) -- caught only by a
-- multi-chapter, `linenumbers=continuous` stress test; a single-chapter
-- test document has no earlier page break to trigger it and cannot
-- surface this. `M.number_lines` (below) now only clears the flag once
-- it has actually been applied to a real, glyph-bearing line
-- (`consumed_heading_flag`) -- seeing a ghost firing while the flag is
-- set now correctly leaves it set for the NEXT firing to try again.
-- Confirmed fixed with the same debug probe, and separately with a
-- deliberately 2- and 3-line-wrapping chapter title (every physical line
-- of a wrapped heading is correctly marked, since the flag applies to
-- every real line a single firing's vlist contains, not once per line).
--
-- `heading/endgroup/<level>` (a second hook, also set up in
-- marginalreader.cls) remains as a safety net clearing the flag
-- unconditionally: it covers the residual, genuinely pathological case
-- of an empty title producing no paragraph -- and therefore no
-- `post_linebreak_filter` firing, ghost or real -- at all, which would
-- otherwise leave the flag stuck indefinitely.
--
-- `groupcode` (post_linebreak_filter's second argument) was considered
-- and rejected as a heading-vs-body discriminator: empirically, EVERY
-- paragraph in this class -- chapter titles, section titles, body text,
-- and `\parbox`-nested margin-note text alike -- reports the same empty
-- groupcode (`""`, i.e. "bottom level"). It carries no information useful
-- here.
--
-- Horizontal placement
-- ---------------------
-- A "line" hlist's own local coordinate origin (x=0) is the text
-- column's left edge, for both recto and verso pages (geometry.sty's
-- \oddsidemargin/\evensidemargin already absorb the parity difference --
-- this is the same invariant `\mr@marginitem`'s own placement math in
-- marginalreader.cls relies on). A box's `shift` field displaces it
-- HORIZONTALLY when the box sits in a VERTICAL list (the \moveleft/
-- \moveright convention -- see marginalreader-margin.lua's
-- M.process_page header comment for the same fact, used the same way).
-- So, per the design spec (sec. 6): the
-- number's RIGHT edge sits `line_sep` to the left
-- of x=0 on recto pages (flush right against the text column, numbers of
-- different digit counts therefore right-aligned against that shared
-- edge); its LEFT edge sits `line_sep` to the right of x=`text_width` on
-- verso pages (flush left against the text column's right edge). Recto/
-- verso is approximated via `tex.count[0]` (the page-number count
-- register, i.e. `\count0`/`\value{page}`) at the point each paragraph is
-- broken -- the same approximation `\mr@marginitem` already documents
-- and accepts for the identical reason (the true page a given line lands
-- on is only certain at shipout time, well after this callback runs).
--
-- Vertical placement / zero extent
-- ----------------------------------
-- The inserted number box's width, height AND depth are all forced to 0
-- (mirroring `\mr@marginitem`'s own \wd/\ht/\dp-zeroing convention
-- exactly). This is not merely "tidy" -- it is required for correctness:
-- `insert_before` (used to splice the number box into the target line's
-- paragraph vlist) is a raw linked-list operation, not the
-- `append_to_vlist` procedure that inserts baselineskip glue when a NEW
-- box is appended to a vertical list. A number box with real (nonzero)
-- height/depth would therefore add its own extent as pure, uncompensated
-- extra vertical space at that point -- there is no automatic glue
-- inserted, or skipped, on this module's behalf. Zeroing all three
-- dimensions is what makes the box invisible to vertical spacing while
-- its (unrelated to wd/ht/dp) actual glyph content still paints at its
-- real position -- the same "declared extent vs. painted content" split
-- `\mr@marginitem`'s comment block in marginalreader.cls documents for
-- exactly the same reason.
--
-- This module always splices the number box immediately BEFORE the
-- target line, including when the target is its paragraph's first line
-- (e.g. line 1 of the first paragraph after a heading -- the common case
-- with the default `firstlinenum=1`). A first draft of this comment
-- worried that case would be different -- reasoning that the number box
-- would then become the nominal first item of the vlist this callback
-- returns, so whatever computes the gap between the PRECEDING material
-- (a heading, or the previous paragraph) and this paragraph would use
-- the number box's own height (0) rather than the real first line's
-- height, pushing the paragraph up by the difference. Checked directly
-- rather than left as a theoretical worry (the development notes): built a
-- controlled test with two otherwise-identical headings/paragraph pairs,
-- one with an ordinary (unnumbered) first line and one engineered so the
-- SAME first line is numbered, and compared the heading-to-paragraph gap
-- with `pdftotext -bbox` -- identical to the point of the tool's
-- printed precision, both after a heading and between two ordinary
-- paragraphs (`\parskip`-governed spacing). No fix needed: the leading
-- interline glue before a paragraph's first line is attached by the
-- paragraph builder itself, as part of the very vlist this callback
-- receives -- i.e. already fixed, using the real surrounding context,
-- before this module ever runs -- so the number box (spliced in AFTER
-- that leading glue, since it sits right before the first LINE, not
-- before the whole vlist) never actually becomes what an outer
-- computation would treat as this paragraph's leading edge.
local M = {}
-- Attribute used to re-identify number boxes at pre_output_filter time
-- for the recto/verso correction pass -- see "Recto/verso correction
-- pass" below. The value stored is the box's own natural (pre-shift)
-- width in sp, needed again to recompute its horizontal shift.
M.width_attr = luatexbase.new_attribute("mr_linenum_width")
-- ---------------------------------------------------------------------
-- Configuration (set by marginalreader.cls, \AtBeginDocument)
-- ---------------------------------------------------------------------
M.enabled = false
M.increment = 5
M.first_line = 1
M.continuous = false
M.inner_margin = 0 -- sp; documents the geometry constraint the 3pt-sep
-- placement below is expected to comfortably fit
-- inside (see "Horizontal placement" above) --
-- not consulted directly by the placement formula.
M.line_sep = 0 -- sp
M.text_width = 0 -- sp
M.is_twoside = true
M.font_id = nil -- set via M.set_font, from \linenumfont
-- Running state
M.line_counter = 0
M.next_is_heading = false
function M.configure(opts)
for k, v in pairs(opts) do
M[k] = v
end
end
function M.set_font(id)
M.font_id = id
end
function M.reset_counter()
M.line_counter = 0
end
function M.set_enabled(val)
M.enabled = val
end
function M.mark_heading_next()
M.next_is_heading = true
end
function M.clear_heading_flag()
M.next_is_heading = false
end
-- ---------------------------------------------------------------------
-- Node-type constants (looked up once)
-- ---------------------------------------------------------------------
local hlist_t = node.id("hlist")
local glyph_t = node.id("glyph")
-- ---------------------------------------------------------------------
-- Helpers
-- ---------------------------------------------------------------------
-- Is `c` a Unicode Private Use Area codepoint (BMP PUA, or either
-- supplementary PUA plane)? See line_has_glyph below for why this is
-- checked.
local function is_pua(c)
return (c >= 0xE000 and c <= 0xF8FF)
or (c >= 0xF0000 and c <= 0xFFFFD)
or (c >= 0x100000 and c <= 0x10FFFD)
end
-- Does this "line" hlist contain at least one real, visible-text glyph?
-- See the "Filtering for real text lines" note above (point 2) for the
-- background this exists against.
--
-- A plain "contains any glyph node at all" check (this function's first
-- version) turned out to still be fooled, on THIS installation, by a
-- further, more specific artefact than the entirely-glyph-free "ghost"
-- lines described there: single-glyph "line" hlists whose one glyph is a
-- Private Use Area codepoint (observed: U+F02DF, U+F02E0 -- Supplementary
-- PUA-A), clustering around the same page-break-adjacent points as the
-- glyph-free ghost lines. Root cause not chased down (out of scope --
-- the same "make it harmless by construction" approach applies as for
-- the glyph-free case above), but a font-shaping-machinery-internal
-- marker of some kind is the obvious suspect: this engine is LuaHBTeX
-- (HarfBuzz-shaped), and PUA codepoints are a standard place for a
-- shaping engine to stash an internal, not-meant-to-be-seen marker
-- glyph, exactly like this class's own body font's OpenType features
-- (smcp for \spacedlowsmallcaps, active on every heading in this
-- document) can themselves produce. The glyph's `subtype` field was
-- tried first as a possible discriminator and rejected: on this
-- installation it reads 65280 (nowhere near the documented glyph-subtype
-- flag range 0-31) for BOTH the PUA artefact AND ordinary real-text
-- glyphs alike (confirmed by dumping every glyph of a correctly-counted
-- "Resumed line one." body line, the development notes) -- not a usable
-- signal here. The codepoint itself is: real body text in this class's
-- Latin-script test documents has no legitimate reason to ever set a
-- PUA codepoint, so requiring at least one NON-PUA glyph is a safe,
-- specific way to tell a genuine text line from this artefact without
-- needing to fully explain its origin.
local function line_has_glyph(linebox)
local n = node.direct.getlist(linebox)
while n do
if node.direct.getid(n) == glyph_t and not is_pua(node.direct.getchar(n)) then
return true
end
n = node.direct.getnext(n)
end
return false
end
-- Build a zero-extent hlist containing `num`'s digits, set in
-- M.font_id, using that font's own character metrics, ready to be
-- spliced immediately before `target` (the "line" hlist being numbered)
-- via `insert_before`. `target_height` is `target`'s own getheight(),
-- needed for the vertical correction below. Returns the box and its
-- PRE-zeroing natural width (needed by the caller for recto-side
-- right-alignment; see "Horizontal placement" above), or nil if no font
-- has been configured yet or the font is missing digit glyphs.
--
-- Two-box structure, and why: this callback splices the returned box
-- directly before `target` with NO glue node between them (a plain
-- `insert_before`, not the glue-inserting `append_to_vlist` procedure --
-- see the module header note "Vertical placement / zero extent"). Given
-- boxes A directly followed by B with no intervening glue, standard box-
-- stacking places B's baseline at `A.baseline + A.depth + B.height` --
-- so with this returned box's height/depth forced to 0 (required so
-- `target` itself is not displaced -- see that same header note), the
-- returned box's OWN baseline necessarily ends up `target_height` ABOVE
-- target's real baseline, not level with it. Confirmed empirically
-- during development (the development notes): the digit glyphs, if drawn
-- directly on that outer box's baseline, render floating visibly above
-- the numbered line -- `pdftotext -bbox` showed a ~7.6pt discrepancy,
-- consistently, on every numbered line, not just paragraph-opening ones.
--
-- Fixed with two nested boxes rather than one: `inner` (the actual digit
-- glyphs, hpacked to its natural size) sits inside `outer` (a fresh,
-- separate zero-extent hlist, built the same direct.new-plus-manual-
-- fields way marginalreader-margin.lua's own M.process_page builds ITS
-- zero-extent wrapper). `outer`'s `shift` -- a box-in-VERTICAL-list, so
-- HORIZONTAL displacement -- does the recto/verso margin placement, same
-- as a single-box design would. `inner`'s `shift` -- a box-in-outer's-
-- (horizontal) content list, so VERTICAL displacement, the \raise/\lower
-- convention -- is set to `target_height`, positive (= lower, i.e.
-- \lower's direction, confirmed against this installation) to pull the
-- glyphs back down by exactly the gap the paragraph above derives:
-- rendering them at `outer.baseline + target_height`, which is exactly
-- target's real baseline. `outer` itself stays net-zero height+depth, so
-- `target`'s own position is still completely unaffected.
local function build_number_box(num, target_height)
if not M.font_id then return nil end
local fnt = font.fonts[M.font_id]
if not fnt or not fnt.characters then return nil end
local chars = fnt.characters
local s = tostring(num)
local chain_head, chain_tail = nil, nil
for i = 1, #s do
local c = string.byte(s, i)
local ci = chars[c]
if ci then
local g = node.direct.new("glyph")
node.direct.setfield(g, "subtype", 1) -- "character" (node.subtypes("glyph"))
node.direct.setfont(g, M.font_id)
node.direct.setchar(g, c)
node.direct.setfield(g, "width", ci.width or 0)
node.direct.setfield(g, "height", ci.height or 0)
node.direct.setfield(g, "depth", ci.depth or 0)
if chain_tail then
node.direct.setlink(chain_tail, g)
else
chain_head = g
end
chain_tail = g
end
end
if not chain_head then return nil end
local inner = node.direct.hpack(chain_head)
node.direct.setfield(inner, "dir", "TLT") -- see marginalreader-margin.lua's
-- M.process_page header comment:
-- freshly built box nodes need
-- this set explicitly or the
-- PDF backend warns ("forcing
-- bad dir -1 to TLT").
local natural_width = node.direct.getwidth(inner)
node.direct.setfield(inner, "shift", target_height)
local outer = node.direct.new("hlist")
node.direct.setfield(outer, "subtype", 2) -- "box" (node.subtypes("hlist")),
-- i.e. explicitly NOT "line" --
-- see the module header note on
-- why hlist subtype matters here.
node.direct.setfield(outer, "dir", "TLT")
node.direct.setfield(outer, "head", inner)
node.direct.setfield(outer, "width", 0)
node.direct.setfield(outer, "height", 0)
node.direct.setfield(outer, "depth", 0)
-- Marked for the recto/verso correction pass -- see "Recto/verso
-- correction pass" in the module header comment and M.fix_page below.
node.direct.set_attribute(outer, M.width_attr, natural_width)
return outer, natural_width
end
-- ---------------------------------------------------------------------
-- Callback
-- ---------------------------------------------------------------------
-- post_linebreak_filter signature: function(head, groupcode) -> head
-- (see LuaTeX reference manual sec. 9.5; fires once per paragraph, with
-- that paragraph's already-broken vlist as `head`).
-- Flag: set true while typesetting margin content (\mr@marginitem's
-- \parbox), so this callback skips those paragraphs. Without this,
-- lines inside margin glosses/blocks get counted as body text lines.
M.in_margin = false
-- Depth counter: > 0 inside display elements (fullwidth, figure*,
-- table*, figure, table, textfigure), whose content is not body text
-- -- the design spec's line numbering counts "body text lines only,
-- skipping headings, display elements, and vertical skips". A depth
-- counter rather than a boolean so nested display environments (e.g.
-- a textfigure inside a fullwidth) unwind correctly. Incremented /
-- decremented via M.display_push/M.display_pop by those environments
-- in marginalreader.cls.
M.display_depth = 0
function M.display_push()
M.display_depth = M.display_depth + 1
end
function M.display_pop()
M.display_depth = M.display_depth - 1
if M.display_depth < 0 then M.display_depth = 0 end
end
-- Debug helper (MR_DEBUG=1): first few characters of a line's glyphs,
-- so the log shows WHICH lines the counter counted.
local function line_text(linebox)
local out, count = {}, 0
local n = node.direct.getlist(linebox)
while n and count < 40 do
if node.direct.getid(n) == glyph_t then
local c = node.direct.getchar(n)
if not is_pua(c) and c >= 32 and c < 0x10000 then
out[#out + 1] = utf8.char(c)
count = count + 1
end
elseif node.direct.getid(n) == node.id("glue") then
out[#out + 1] = " "
end
n = node.direct.getnext(n)
end
return table.concat(out)
end
function M.number_lines(head, groupcode)
if not M.enabled then return head end
if M.in_margin then return head end
if M.display_depth > 0 then return head end
local is_heading_par = M.next_is_heading
local d_head = node.direct.todirect(head)
-- Recto/verso approximation -- see "Horizontal placement" above.
local recto
if M.is_twoside then
recto = (tex.count[0] % 2) == 1
else
recto = true
end
local consumed_heading_flag = false
local n = d_head
while n do
if node.direct.getid(n) == hlist_t
and node.direct.getsubtype(n) == 1
and line_has_glyph(n) then
if is_heading_par then
-- Heading line: not counted, not numbered. Only NOW -- having
-- actually found a real line to apply it to -- is the flag
-- considered consumed (see the comment below on
-- `consumed_heading_flag` for why this matters).
consumed_heading_flag = true
if os.getenv("MR_DEBUG") then
texio.write_nl(string.format("MRLINES heading (skipped): %q",
line_text(n)))
end
else
M.line_counter = M.line_counter + 1
if os.getenv("MR_DEBUG") then
texio.write_nl(string.format("MRLINES %d: %q",
M.line_counter, line_text(n)))
end
if M.line_counter == M.first_line
or (M.line_counter > M.first_line
and M.line_counter % M.increment == 0) then
local numbox, natural_width =
build_number_box(M.line_counter, node.direct.getheight(n))
if numbox then
-- Horizontal (recto/verso) placement only -- `outer`'s
-- width/height/depth are already zeroed, and the vertical
-- baseline correction already applied to `inner`, by
-- build_number_box itself (see that function's header
-- comment).
local shift
if recto then
shift = -(M.line_sep + natural_width)
else
shift = M.text_width + M.line_sep
end
node.direct.setfield(numbox, "shift", shift)
d_head = node.direct.insert_before(d_head, n, numbox)
end
end
end
end
n = node.direct.getnext(n)
end
-- Only clear the flag once it has actually been applied to a real
-- line (`consumed_heading_flag`), NOT simply because this call started
-- with it set. Discovered necessary empirically (the development notes,
-- debug-instrumented): the module header note's "ghost" glyph-free
-- post_linebreak_filter firings (see "Filtering for real text lines",
-- point 2) are not confined to end-of-document -- they were also
-- observed clustering around ordinary page breaks, which land BETWEEN
-- `heading/begingroup/chapter` (marginalreader.cls) setting this flag
-- and `\chapter`'s own title paragraph actually running (chapter
-- openings force a page break as part of their own startup sequence).
-- An earlier version of this function cleared the flag unconditionally
-- whenever `is_heading_par` was true on entry -- which a glyph-free
-- ghost call, having nothing to mark, would still do, consuming the
-- flag before the real title paragraph's own call ever saw it, and
-- silently miscounting that chapter's title as an ordinary body line
-- (confirmed with a debug post_linebreak_filter probe dumping
-- M.line_counter at every firing: the counter incremented by exactly
-- one extra step at every second-and-later \chapter, i.e. every
-- \chapter whose page break has a real chance of producing a ghost
-- firing between begingroup and the title itself; the first chapter of
-- a document -- nothing before it to force a page break from -- was
-- unaffected, which is what made this easy to miss with only a single-
-- chapter test document). `heading/endgroup/<level>` (marginalreader
-- .cls) remains the correct safety net for the residual, genuinely
-- pathological case (an empty title, producing no lines at all).
if is_heading_par and consumed_heading_flag then
M.next_is_heading = false
end
return node.direct.tonode(d_head)
end
-- ---------------------------------------------------------------------
-- Recto/verso correction pass
-- ---------------------------------------------------------------------
-- `M.number_lines` (above) decides recto/verso from `tex.count[0]`
-- (`\count0`, the page-number count register) at `post_linebreak_filter`
-- time -- i.e. while the paragraph containing the numbered line is being
-- broken into lines, which happens BEFORE TeX's page builder has decided
-- where page breaks actually fall. `\count0` only advances when a page
-- is actually shipped out, so for a numbered line that lands within
-- roughly the page builder's own lookahead of an upcoming page break,
-- this reads the PREVIOUS page's parity, not the page the line will
-- actually end up on.
--
-- This is the same fundamental timing gap `\mr@marginitem`
-- (marginalreader.cls) already documents and accepts for its own
-- `\ifodd\value{page}` check ("a gloss anchored right at a page break
-- can occasionally land shifted to the wrong side"). Measured here,
-- empirically, with a multi-page stress test (the development notes): it is
-- narrow in exactly the way that comment describes -- of a page's worth
-- of numbered lines, only the FIRST one immediately after a page break
-- was ever affected; every other numbered line on the same page (well
-- clear of the boundary) came out correct.
--
-- Unlike `\mr@marginitem`, this narrow case is corrected outright rather
-- than just accepted, since it is cheap to fix and a number on the
-- outright WRONG side of the page (rather than merely shifted a little)
-- reads as a more obviously-broken mistake. `M.number_lines` marks every
-- number box it creates with `M.width_attr` (value = the box's own
-- natural width, needed again below). `M.fix_page`, registered on
-- `pre_output_filter` -- the same callback marginalreader-margin.lua's
-- own M.process_page already uses, for the same underlying reason: by
-- the time a page's material is boxed up for \output, page-breaking for
-- THAT page is completely finished, so `tex.count["c@page"]` (the same
-- page-number source M.process_page itself already relies on) is
-- authoritative -- walks that page's own node list, finds every box
-- carrying the attribute, and recomputes its shift with the now-certain
-- parity. Registered as an independent callback (own id string):
-- luatexbase chains multiple callbacks under the same name, so this
-- does not disturb marginalreader-margin.lua's own pre_output_filter
-- registration, and no ordering between the two matters -- they touch
-- completely disjoint nodes (this one only ever touches boxes carrying
-- M.width_attr, which only M.number_lines ever sets).
--
-- pre_output_filter's signature is
-- function(head, groupcode, size, packtype, maxdepth, direction)
-- return true | false | <node> newhead
-- (see LuaTeX reference manual sec. 9.5.13, and the identical note on
-- marginalreader-margin.lua's own M.process_page). Field mutation on
-- nodes already in `head` needs no restructuring of the list itself, so
-- -- unlike M.process_page, which splices in brand new nodes -- this
-- never needs to change what `head`'s own first node is.
function M.fix_page(head, groupcode, size, packtype, maxdepth, direction)
local page = tex.count["c@page"]
local recto
if M.is_twoside then
recto = (page % 2) == 1
else
recto = true
end
local d_head = node.direct.todirect(head)
local n = d_head
while n do
if node.direct.getid(n) == hlist_t then
local w = node.direct.get_attribute(n, M.width_attr)
if w then
local shift
if recto then
shift = -(M.line_sep + w)
else
shift = M.text_width + M.line_sep
end
node.direct.setfield(n, "shift", shift)
end
end
n = node.direct.getnext(n)
end
return head
end
-- ---------------------------------------------------------------------
-- Registration
-- ---------------------------------------------------------------------
-- Registered unconditionally (regardless of the `linenumbers` class
-- option's initial value) so that `\linenumbering{on}` reliably works
-- even in a document that starts with `linenumbers=false` -- the
-- `M.enabled` check at the top of M.number_lines is the actual on/off
-- switch; the callback registration itself is not.
M.registered = false
function M.register()
if M.registered then return end
luatexbase.add_to_callback("post_linebreak_filter", M.number_lines, "marginalreader.linenums")
luatexbase.add_to_callback("pre_output_filter", M.fix_page, "marginalreader.linenums.fixpage")
M.registered = true
end
return M