ctrl-kd 4.7.0__tar.gz → 4.7.1__tar.gz

{ctrl_kd-4.7.0/src/ctrl_kd.egg-info → ctrl_kd-4.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ctrl-kd
-Version: 4.7.0
+Version: 4.7.1
 Summary: Convert WordStar 4-7 documents and print-to-disk files to text, Markdown, HTML, RTF, or PDF. ^KD: save and done.
 Author: Jon Michaels
 License: MIT

{ctrl_kd-4.7.0 → ctrl_kd-4.7.1/src/ctrl_kd.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ctrl-kd
-Version: 4.7.0
+Version: 4.7.1
 Summary: Convert WordStar 4-7 documents and print-to-disk files to text, Markdown, HTML, RTF, or PDF. ^KD: save and done.
 Author: Jon Michaels
 License: MIT

{ctrl_kd-4.7.0 → ctrl_kd-4.7.1}/src/ctrlkd/__init__.py

@@ -8,4 +8,4 @@ from .pdf import emit_pdf                        # registers the 'pdf' format
 from .convert import convert, select_notes, DEFAULT_NOTE_KINDS, ALL_NOTE_KINDS
 from .info import document_info
 
-__version__ = '4.7.0'
+__version__ = '4.7.1'

{ctrl_kd-4.7.0 → ctrl_kd-4.7.1}/src/ctrlkd/pdf.py

@@ -750,7 +750,21 @@ def _checkpoints_by_page(checkpoints, pages):
     trailing blanks: a page of nothing but blank lines ends up empty, with
     no `bi` on it at all, which is precisely the shape a leading blank run
     makes. A page that never got one (a synthetic or degenerate page)
-    inherits the last real position rather than resetting the walk."""
+    inherits the last real position rather than resetting the walk.
+
+    A PAGE WITH NO POSITION AT ALL -- not even an inherited one, because no
+    earlier page had one either -- FALLS BACK TO THE BLOCK-RANGE RULE, the
+    granularity this walk replaced on 2026-09-14: the last checkpoint whose
+    block index is at or before the highest block index this page carries.
+    Leaving it on the seeded checkpoint 0 instead silently answered "the
+    document's opening default" for a page that plainly reads further in,
+    and the document's own `.op` was never consulted: `samples/LYING.WS`
+    numbered all three of its pages where real WordStar 7 numbers none of
+    them, because the footnote paginator sets no `read_pos` and LYING's
+    `.op` is checkpoint 1 (research: "Why real WS7 prints no page number on
+    some documents", 2026-09-15). Never moves BACKWARD -- the walk's
+    consumers (`_resolve_page_numbers`' re-anchor test) read a falling index
+    as a new anchor."""
     out, last, pos = [], 0, None
     for pg in pages:
         pos = getattr(pg, 'read_pos', None) or pos
@@ -761,10 +775,38 @@ def _checkpoints_by_page(checkpoints, pages):
                 if not (cp_bi < pos_bi or (cp_bi == pos_bi and cp_li < pos_count)):
                     break
                 last = idx
+        else:
+            last = max(last, _checkpoint_by_block(checkpoints, pg))
         out.append(last)
     return out
 
 
+def _checkpoint_by_block(checkpoints, pg):
+    """The BLOCK-RANGE answer for one page: the index of the last checkpoint
+    whose block index is at or before the highest block index the page
+    carries -- `_pgnum_at`/`_pl_at`'s own "last checkpoint at or before this
+    block wins" contract, as an index rather than a value so the positional
+    walk above can keep using it as a floor.
+
+    A page carrying no `.bi` at all (nothing but emitter-made lines -- a
+    footnote-area-only page, a blank page whose trailing blanks were
+    stripped) has no block range to test, so it keeps whatever the walk
+    already had."""
+    top = None
+    for ln in pg:
+        bi = getattr(ln, 'bi', None)
+        if bi is not None and (top is None or bi > top):
+            top = bi
+    if top is None:
+        return 0
+    last = 0
+    for idx in range(1, len(checkpoints)):
+        if checkpoints[idx][0] > top:
+            break
+        last = idx
+    return last
+
+
 # no `\b` after the 2-letter code (matches `_PN_CMD_RE`'s own shape,
 # immediately below in this same module): a real WS7 file overwhelmingly
 # writes `.pn0`/`.pn22`/`.hm3` with NO space before the argument, and `\b`
@@ -3795,6 +3837,18 @@ def _paginate_printed_notes(doc, cap, width, pix_results=None, pictures='off',
     # footnote AREA or with plain BODY text -- `_endnote_pages` needs the
     # distinction to decide whether a blank line precedes the first endnote.
     last_page_has_area = False
+    # The same running per-block line tally `_doc_to_pagelines`' paginator
+    # keeps, for the same consumer: `_checkpoints_by_page` asks each page
+    # HOW FAR INTO THE DOCUMENT it had read when it closed, and a page built
+    # here never answered -- so a document with footnotes lost its own
+    # `.op`/`.pn`/`.pg` and took the seeded "numbering ON" default.
+    # `samples/LYING.WS` numbered all three pages where real WS7 numbers
+    # none (research: "Why real WS7 prints no page number on some
+    # documents", 2026-09-15). Counted off the BODY only: a footnote area's
+    # lines are the emitter's own, and the reference that pulled them down
+    # here was already counted on the body line carrying it.
+    read_tally = {}
+    read_pos = None
     i, n = 0, len(stream)
     while i < n:
         body, entries, is_terminal = [], [], False
@@ -3838,6 +3892,10 @@ def _paginate_printed_notes(doc, cap, width, pix_results=None, pictures='off',
             if body and body_len + cost + _area_size(entries) > _col_cap():
                 break                            # natural page-full: line moves on
             body.append(spans)
+            bi_here = getattr(spans, 'bi', None)
+            if bi_here is not None:
+                read_tally[bi_here] = read_tally.get(bi_here, 0) + 1
+                read_pos = (bi_here, read_tally[bi_here])
             body_len += cost
             if i == last_idx:
                 is_terminal = True
@@ -3886,7 +3944,9 @@ def _paginate_printed_notes(doc, cap, width, pix_results=None, pictures='off',
             override = target_first - body_y
             if override > 0:
                 area = [PageLine(area[0], lead=override)] + area[1:]
-        pages.append(body + area)
+        closed = NotesPage(body + area)
+        closed.read_pos = read_pos
+        pages.append(closed)
         _advance_column()
         last_page_cost = body_len + _area_size(entries)
         last_page_has_area = bool(entries)
@@ -4182,6 +4242,26 @@ class PageLine(list):
         self.graphic_cells = graphic_cells
 
 
+class NotesPage(list):
+    """A page built by `_paginate_printed_notes`, carrying ONE thing beyond
+    a plain list: the `read_pos` `_checkpoints_by_page` needs.
+
+    Deliberately NOT a `Page`. `Page.__init__` seeds `headers`/`footers` to
+    `{}`, and `_emit_pdf_inner` reads an empty dict as an authoritative "this
+    page has no running head" rather than "no opinion, use the document's"
+    (see `_apply_columns`' own `merged.headers` comment) -- so promoting the
+    notes paginator's plain lists to `Page` would drop a real running head
+    from every footnote-bearing document. This subclass leaves every other
+    attribute undefined, so each `getattr(pg, ..., default)` in the emitters
+    still lands on exactly the default a bare list did."""
+
+    __slots__ = ('read_pos',)
+
+    def __init__(self, seq=()):
+        super().__init__(seq)
+        self.read_pos = None
+
+
 class Page(list):
     """One paginated page: a list of PageLines plus the running head and
     foot IN FORCE when this page printed (replayed from doc.hf_events).
@@ -6830,9 +6910,18 @@ def _attach_head_foot_lines_printed(doc, pages, size):
             # reads this SAME `pages` list a few lines later -- keeps
             # seeing byte-identical `getattr(pl, 'headers', None)`
             # answers; PDF bytes do not move.
+            # `read_pos` carried across too (2026-09-15): the notes
+            # paginator now records one, and `_checkpoints_by_page` is
+            # asked the automatic-number question a SECOND time by
+            # `_emit_pdf_inner`'s own render loop, off this very list.
+            # Dropping the position here would let the two answers
+            # disagree about where a `.op`/`.pn` was read -- the same
+            # two-sources-of-truth fault this promotion exists to close.
+            was = getattr(pg, 'read_pos', None)
             pg = Page(pg)
             pg.headers = None
             pg.footers = None
+            pg.read_pos = was
             pages[page_index] = pg
         if resolved['headers']:
             # `style_attrs` (planning #255) is a PDF-render-time concern

{ctrl_kd-4.7.0 → ctrl_kd-4.7.1}/tests/test_pn_page_timing.py

@@ -166,3 +166,128 @@ def test_the_checkpoints_carry_their_line_position():
     cps = pdf._pn_checkpoints(doc)
     assert [c[2] for c in cps][-2:] == [3, 7], cps
     assert cps[-1][1] > cps[-2][1], cps      # the later one read further in
+
+
+# ====== the footnote path reads the document's own `.op` (2026-09-15) ======
+#
+# Research: "Why real WS7 prints no page number on some documents"
+# (jon_vault, 2026-09-15). Real WordStar 7 numbers every page unless the
+# document says otherwise, and `.op` is one of the four things that say
+# otherwise. `samples/LYING.WS` carries `.op` AND a footnote, and the
+# positional walk this file's own Q12 tests introduced printed a number on
+# all three of its pages: a page built by the FOOTNOTE paginator got no
+# `read_pos`, the walk's inner loop never ran, and the answer stayed on the
+# seeded "numbering ON" checkpoint 0 -- the `.op` was never consulted.
+# Across all 308 WS7 captures no document carrying `.op` prints a number,
+# with zero counter-examples, and a whole-corpus sweep finds exactly three
+# documents carrying both a footnote and a numbering-off command (LYING,
+# and two private ones), so these are the whole blast radius.
+
+import os
+
+SAMPLES_DIR = os.path.join(
+    os.path.dirname(os.path.dirname(os.path.abspath(__file__))), 'samples')
+
+# WordStar's own default geometry again, but with no `.ps off`: a document
+# whose ONLY dot command is the one under test, so nothing else can be
+# blamed for the answer.
+PLAIN = b'.pl 66' + HARD + b'.mt 3' + HARD + b'.mb 8' + HARD + b'.po1i' + HARD
+
+
+def _ws7_block(cmd, content=b''):
+    """One WS7 0x1D-delimited block -- the shape
+    tests/test_note_rulings_20260824.py already builds notes with."""
+    count = (len(content) + 4).to_bytes(2, 'little')
+    return b'\x1d' + count + bytes([cmd]) + content + count + b'\x1d'
+
+
+def _footnote(text, number=1):
+    """A one-line FOOTNOTE (note command 0x03) -- the kind that sends a
+    document down `_paginate_printed_notes`, which is the paginator that
+    lost the `.op`."""
+    return _ws7_block(0x03, (1).to_bytes(2, 'little')
+                      + number.to_bytes(2, 'little') + bytes([0x30]) + text)
+
+
+def _foot_digits(data):
+    """Per page, the digit-only chunks drawn on that page's LOWEST print
+    line -- the research note's own install-independent test for "is there
+    an automatic page number here", which assumes no fixed x or y (`.pl`,
+    `.mb`, `.po` and `.pc` all move the real one)."""
+    out = pdf.emit_pdf(core.parse_ws(data), mode='printed')
+    pages = []
+    for stream in re.findall(rb'stream\n(.*?)endstream', out, re.S):
+        rows = {}
+        for x, y, t in re.findall(rb'([\d.]+) ([\d.]+) Td\s*\((.*?)\) Tj', stream):
+            rows.setdefault(float(y), []).append(t.decode('latin-1'))
+        if not rows:
+            pages.append([])
+            continue
+        foot = rows[min(rows)]                  # PDF y grows UPWARD: lowest line
+        pages.append([t for t in foot if t.strip().isdigit()])
+    return pages
+
+
+def test_lying_ws_prints_no_automatic_page_number_on_any_page():
+    """The regression itself, pinned on the bundled public-domain sample.
+    LYING.WS's `.op` is the FIRST LINE OF THE FILE -- it follows the header
+    block's closing 0x1D with no CR LF before it -- and it turns the
+    automatic number off for the whole document. Real WS7's own capture
+    (ws7-prints/v3) prints no number on any of the three pages."""
+    data = open(os.path.join(SAMPLES_DIR, 'LYING.WS'), 'rb').read()
+    doc = core.parse_ws(data)
+    assert doc.notes, 'LYING.WS is the fixture BECAUSE it has a footnote'
+    pages = pdf._doc_to_pagelines(doc, printed=True)
+    on = pdf._pgnum_by_page(pdf._pgnum_checkpoints(doc), pages)
+    assert on == [False] * len(pages), on
+    assert _foot_digits(data) == [[], [], []], _foot_digits(data)
+
+
+def test_a_footnote_document_that_omits_numbers_reads_its_own_op():
+    """The same shape synthetically, so the rule is pinned even if the
+    sample ever changes: `.op`, a footnote, two pages of body."""
+    data = (PLAIN + b'.op' + HARD + b'OPBODY' + _footnote(b'A footnote.')
+            + HARD + _blanks(80) + b'OPTAIL' + HARD)
+    assert _foot_digits(data) == [[], []], _foot_digits(data)
+
+
+def test_a_footnote_document_with_pn_is_still_numbered():
+    """The control, and the half a too-broad fix would break: footnotes have
+    NOTHING to do with the automatic number. 28 numbered WS7 captures carry
+    real footnotes. `.pn` says number the pages, and it still does."""
+    data = (PLAIN + b'.pn 1' + HARD + b'PNBODY' + _footnote(b'A footnote.')
+            + HARD + _blanks(80) + b'PNTAIL' + HARD)
+    assert _foot_digits(data) == [['1'], ['2']], _foot_digits(data)
+
+
+def test_the_footnote_paginator_records_where_each_page_read_to():
+    """The first half of the mechanism: a page built by the notes-aware
+    paginator now carries its own `read_pos`, so it answers the walk
+    directly instead of falling through to the seeded default."""
+    for name, dot in (('LYING.WS', None), (None, b'.pn 1'), (None, b'.op')):
+        if name:
+            data = open(os.path.join(SAMPLES_DIR, name), 'rb').read()
+        else:
+            data = (PLAIN + dot + HARD + b'XBODY' + _footnote(b'A footnote.')
+                    + HARD + _blanks(80) + b'XTAIL' + HARD)
+        doc = core.parse_ws(data)
+        assert pdf._has_placeable_notes(doc), (name, dot)
+        positions = [getattr(pg, 'read_pos', None)
+                     for pg in pdf._doc_to_pagelines(doc, printed=True)]
+        assert all(p is not None for p in positions), (name, dot, positions)
+        assert positions == sorted(positions), (name, dot, positions)
+
+
+def test_a_page_with_no_read_position_falls_back_to_the_block_range_rule():
+    """The second half, and the belt to that brace: a page that carries no
+    read position at all -- a synthetic or degenerate page, from any future
+    paginator -- is answered by block range (the last checkpoint at or
+    before the highest block the page carries), not by the seeded
+    checkpoint 0. Checkpoints here: ON at block 0, OFF at block 2."""
+    checkpoints = [(0, 0, True), (2, 0, False)]
+    early, late = pdf.PageLine([('x', None)]), pdf.PageLine([('y', None)])
+    early.bi, late.bi = 1, 3
+    assert pdf._checkpoints_by_page(checkpoints, [[early], [late]]) == [0, 1]
+    assert pdf._checkpoints_by_page(checkpoints, [[late]]) == [1]
+    # No `.bi` anywhere on the page: nothing to range over, walk unchanged.
+    assert pdf._checkpoints_by_page(checkpoints, [[]]) == [0]