ctrl-kd 1.1.6__tar.gz → 1.2.0__tar.gz

{ctrl_kd-1.1.6/src/ctrl_kd.egg-info → ctrl_kd-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ctrl-kd
-Version: 1.1.6
+Version: 1.2.0
 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
@@ -32,6 +32,8 @@ $ ctrl-kd ESSAY.WS -t html -t rtf       # multiple formats
 $ ctrl-kd ESSAY.WS -t pdf --mode printed # a facsimile of the 1990 printout
 $ ctrl-kd --mode printed LETTER.WS      # line-for-line, as it printed in 1990
 $ ctrl-kd --diagnose MYSTERY.FIL        # what IS this file?
+$ ctrl-kd --comments MEMO.WS            # include the author's hidden comments
+$ ctrl-kd --no-notes PAPER.WS           # body text only, no notes
 ```
 
 ## Why another converter?
@@ -67,9 +69,19 @@ against surviving period printouts of the same documents. Its rules are empirica
 * **WS5+ symmetric blocks** (`0x1D`: real footnotes/endnotes, headings, page
   breaks — machinery added in WS5) are parsed with their nested structure,
   verified against the 86 WordStar 7 documents in Robert J. Sawyer's public
-  WordStar archive: footnotes extract with in-text references (`[^n]` in
-  Markdown), paragraph styles become headings, and 82/86 convert with zero
-  mojibake. More WS5–7 corpora still welcome.
+  WordStar archive. All **four** note kinds WordStar distinguished are read and
+  kept apart — footnote, endnote, annotation, and comment — with in-text
+  references (`[^n]` in Markdown, DPUB-ARIA anchors in HTML, real `\footnote`
+  destinations in RTF). **Comments never appear unless you ask for them**, since
+  WordStar never printed them; `--diagnose` still reports that they exist.
+  Paragraph styles become headings, and 82/86 convert with zero mojibake.
+  More WS5–7 corpora still welcome.
+* **Page geometry** from the file's own `.pl`/`.po`/`.mt`/`.mb`, so `--mode
+  printed` uses the page the author set up rather than an assumed one — and
+  `--diagnose` says whether the size came from the file or from the default.
+  In `printed` mode footnotes are laid out the way WordStar laid them out: at
+  the foot of the page that references them, behind a twenty-dash separator,
+  split across pages with `...Continued...` when they do not fit.
 
 ## Modes
 
@@ -95,6 +107,13 @@ An output format is one function over the parsed document — register it with t
 **[EXTENDING.md](EXTENDING.md)** has the IR contract, a complete worked example
 (BBCode in ~40 lines), and a checklist.
 
+## Siblings
+
+**[soft-return](https://github.com/jonmichaels/soft-return)** — CtrlKD, a Swift
+port of this engine, verified byte-for-byte against this implementation via
+machine-generated test vectors (the two projects found six real bugs in each
+other during the port). It grows the `sr` CLI and the Soft Return macOS app.
+
 ## Lineage
 
 Standing on the shoulders of the tools and documentation that kept WordStar

{ctrl_kd-1.1.6 → ctrl_kd-1.2.0}/README.md

@@ -13,6 +13,8 @@ $ ctrl-kd ESSAY.WS -t html -t rtf       # multiple formats
 $ ctrl-kd ESSAY.WS -t pdf --mode printed # a facsimile of the 1990 printout
 $ ctrl-kd --mode printed LETTER.WS      # line-for-line, as it printed in 1990
 $ ctrl-kd --diagnose MYSTERY.FIL        # what IS this file?
+$ ctrl-kd --comments MEMO.WS            # include the author's hidden comments
+$ ctrl-kd --no-notes PAPER.WS           # body text only, no notes
 ```
 
 ## Why another converter?
@@ -48,9 +50,19 @@ against surviving period printouts of the same documents. Its rules are empirica
 * **WS5+ symmetric blocks** (`0x1D`: real footnotes/endnotes, headings, page
   breaks — machinery added in WS5) are parsed with their nested structure,
   verified against the 86 WordStar 7 documents in Robert J. Sawyer's public
-  WordStar archive: footnotes extract with in-text references (`[^n]` in
-  Markdown), paragraph styles become headings, and 82/86 convert with zero
-  mojibake. More WS5–7 corpora still welcome.
+  WordStar archive. All **four** note kinds WordStar distinguished are read and
+  kept apart — footnote, endnote, annotation, and comment — with in-text
+  references (`[^n]` in Markdown, DPUB-ARIA anchors in HTML, real `\footnote`
+  destinations in RTF). **Comments never appear unless you ask for them**, since
+  WordStar never printed them; `--diagnose` still reports that they exist.
+  Paragraph styles become headings, and 82/86 convert with zero mojibake.
+  More WS5–7 corpora still welcome.
+* **Page geometry** from the file's own `.pl`/`.po`/`.mt`/`.mb`, so `--mode
+  printed` uses the page the author set up rather than an assumed one — and
+  `--diagnose` says whether the size came from the file or from the default.
+  In `printed` mode footnotes are laid out the way WordStar laid them out: at
+  the foot of the page that references them, behind a twenty-dash separator,
+  split across pages with `...Continued...` when they do not fit.
 
 ## Modes
 
@@ -76,6 +88,13 @@ An output format is one function over the parsed document — register it with t
 **[EXTENDING.md](EXTENDING.md)** has the IR contract, a complete worked example
 (BBCode in ~40 lines), and a checklist.
 
+## Siblings
+
+**[soft-return](https://github.com/jonmichaels/soft-return)** — CtrlKD, a Swift
+port of this engine, verified byte-for-byte against this implementation via
+machine-generated test vectors (the two projects found six real bugs in each
+other during the port). It grows the `sr` CLI and the Soft Return macOS app.
+
 ## Lineage
 
 Standing on the shoulders of the tools and documentation that kept WordStar

{ctrl_kd-1.1.6 → ctrl_kd-1.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ctrl-kd"
-version = "1.1.6"
+version = "1.2.0"
 description = "Convert WordStar 4-7 documents and print-to-disk files to text, Markdown, HTML, RTF, or PDF. ^KD: save and done."
 readme = "README.md"
 license = {text = "MIT"}

{ctrl_kd-1.1.6 → ctrl_kd-1.2.0/src/ctrl_kd.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ctrl-kd
-Version: 1.1.6
+Version: 1.2.0
 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
@@ -32,6 +32,8 @@ $ ctrl-kd ESSAY.WS -t html -t rtf       # multiple formats
 $ ctrl-kd ESSAY.WS -t pdf --mode printed # a facsimile of the 1990 printout
 $ ctrl-kd --mode printed LETTER.WS      # line-for-line, as it printed in 1990
 $ ctrl-kd --diagnose MYSTERY.FIL        # what IS this file?
+$ ctrl-kd --comments MEMO.WS            # include the author's hidden comments
+$ ctrl-kd --no-notes PAPER.WS           # body text only, no notes
 ```
 
 ## Why another converter?
@@ -67,9 +69,19 @@ against surviving period printouts of the same documents. Its rules are empirica
 * **WS5+ symmetric blocks** (`0x1D`: real footnotes/endnotes, headings, page
   breaks — machinery added in WS5) are parsed with their nested structure,
   verified against the 86 WordStar 7 documents in Robert J. Sawyer's public
-  WordStar archive: footnotes extract with in-text references (`[^n]` in
-  Markdown), paragraph styles become headings, and 82/86 convert with zero
-  mojibake. More WS5–7 corpora still welcome.
+  WordStar archive. All **four** note kinds WordStar distinguished are read and
+  kept apart — footnote, endnote, annotation, and comment — with in-text
+  references (`[^n]` in Markdown, DPUB-ARIA anchors in HTML, real `\footnote`
+  destinations in RTF). **Comments never appear unless you ask for them**, since
+  WordStar never printed them; `--diagnose` still reports that they exist.
+  Paragraph styles become headings, and 82/86 convert with zero mojibake.
+  More WS5–7 corpora still welcome.
+* **Page geometry** from the file's own `.pl`/`.po`/`.mt`/`.mb`, so `--mode
+  printed` uses the page the author set up rather than an assumed one — and
+  `--diagnose` says whether the size came from the file or from the default.
+  In `printed` mode footnotes are laid out the way WordStar laid them out: at
+  the foot of the page that references them, behind a twenty-dash separator,
+  split across pages with `...Continued...` when they do not fit.
 
 ## Modes
 
@@ -95,6 +107,13 @@ An output format is one function over the parsed document — register it with t
 **[EXTENDING.md](EXTENDING.md)** has the IR contract, a complete worked example
 (BBCode in ~40 lines), and a checklist.
 
+## Siblings
+
+**[soft-return](https://github.com/jonmichaels/soft-return)** — CtrlKD, a Swift
+port of this engine, verified byte-for-byte against this implementation via
+machine-generated test vectors (the two projects found six real bugs in each
+other during the port). It grows the `sr` CLI and the Soft Return macOS app.
+
 ## Lineage
 
 Standing on the shoulders of the tools and documentation that kept WordStar

{ctrl_kd-1.1.6 → ctrl_kd-1.2.0}/src/ctrl_kd.egg-info/SOURCES.txt

@@ -8,6 +8,7 @@ src/ctrl_kd.egg-info/entry_points.txt
 src/ctrl_kd.egg-info/top_level.txt
 src/ctrlkd/__init__.py
 src/ctrlkd/cli.py
+src/ctrlkd/convert.py
 src/ctrlkd/core.py
 src/ctrlkd/emit.py
 src/ctrlkd/pdf.py

{ctrl_kd-1.1.6 → ctrl_kd-1.2.0}/src/ctrlkd/__init__.py

@@ -3,10 +3,6 @@ from .core import detect, parse, parse_ws, parse_printstream, Document, Block, L
 from .emit import (emit_text, emit_markdown, emit_html, emit_rtf,
                    emitter, get_emitter, formats, load_plugins)
 from .pdf import emit_pdf                        # registers the 'pdf' format
+from .convert import convert, select_notes, DEFAULT_NOTE_KINDS, ALL_NOTE_KINDS
 
-__version__ = '1.1.6'
-
-def convert(data: bytes, to: str = 'markdown', mode: str = 'modern',
-            encoding: str = 'cp437', **options) -> str:
-    """One-call API: bytes in, converted string out."""
-    return get_emitter(to)['fn'](parse(data, encoding=encoding), mode, **options)
+__version__ = '1.2.0'

{ctrl_kd-1.1.6 → ctrl_kd-1.2.0}/src/ctrlkd/cli.py

@@ -8,6 +8,7 @@
 """
 import argparse, json, os, sys
 from . import core, emit
+from .convert import DEFAULT_NOTE_KINDS   # module attr, not the re-exported convert()
 
 def diagnose(path, data):
     det = core.detect(data)
@@ -17,7 +18,31 @@ def diagnose(path, data):
         info.update({k: doc.meta[k] for k in
                      ('margin_estimate', 'dot_commands', 'unknown_codes', 'columnar')})
         info['paragraphs'] = sum(1 for b in doc.blocks if b.kind == 'para')
-        info['footnotes'] = len(doc.footnotes)
+        # note kinds, counted separately (footnote/endnote/annotation/comment)
+        # rather than flattened, so a rescue tool can tell a file has hidden
+        # comments even when this run is only converting to plain text
+        info['notes'] = {kind: sum(1 for n in doc.notes if n.kind == kind)
+                         for kind in ('footnote', 'endnote', 'annotation', 'comment')}
+        # unrecognised symmetrical-sequence types: preserved, not silently
+        # dropped, so --diagnose can report them instead of going quiet
+        info['unknown_blocks'] = [
+            {'type': f'0x{u.cmd:02x}' if u.cmd >= 0 else 'malformed',
+             'offset': u.offset, 'length': len(u.data)}
+            for u in doc.unknown_blocks]
+        # page geometry from the file's own dot commands, with provenance --
+        # a caller must be able to say "Legal (from file)" vs "Letter (default)"
+        info['page'] = doc.meta.get('page')
+        # .PT/.PSA/.PSB are WordTsar's inventions, not WordStar commands: their
+        # presence identifies who WROTE the file, not how it is encoded
+        if doc.meta.get('producer'):
+            info['producer'] = doc.meta['producer']
+    elif det['variant'] == 'printstream':
+        doc = core.parse(data)
+        # damage WordStar itself introduced at print time (comments + the
+        # ASCII/ASC256/PRVIEW/WS4 drivers truncated the rest of the line);
+        # reported so it reads as a 1990s defect, not our parse failing
+        if doc.meta.get('comment_bug'):
+            info['comment_bug'] = doc.meta['comment_bug']
     return info
 
 def main(argv=None):
@@ -40,11 +65,20 @@ def main(argv=None):
                     help='override detection')
     ap.add_argument('--encoding', default='cp437',
                     help='byte encoding of the source (default: cp437)')
+    ap.add_argument('--no-notes', action='store_true',
+                    help='omit footnotes, endnotes and annotations from the output')
+    ap.add_argument('--comments', action='store_true',
+                    help="include WordStar comments, which it never printed "
+                         "(author's asides, hidden since the file was written)")
     ap.add_argument('--diagnose', action='store_true',
                     help='report what the file is (variant, margin, dot commands, '
                          'unknown codes) as JSON; no conversion')
     a = ap.parse_args(argv)
     formats = a.to or ['markdown']
+    if a.no_notes:
+        notes = frozenset()
+    else:
+        notes = set(DEFAULT_NOTE_KINDS) | ({'comment'} if a.comments else set())
     if a.output and (len(a.files) > 1 or len(formats) > 1):
         ap.error('-o works with a single input and a single format; use -d for batch')
 
@@ -69,7 +103,7 @@ def main(argv=None):
         base = os.path.splitext(os.path.basename(path))[0]
         for fmt in formats:
             reg = emit.get_emitter(fmt)
-            out = reg['fn'](doc, a.mode, title=base)
+            out = reg['fn'](doc, a.mode, title=base, notes=notes)
             if a.output:
                 dest = a.output
             else:

ctrl_kd-1.2.0/src/ctrlkd/convert.py

@@ -0,0 +1,37 @@
+"""ctrl-kd conversion API: parse + emit in one call, plus the shared note-kind
+inclusion filter that both `convert()` and each emitter (see emit.py) apply.
+
+WordStar 5+/7 notes come in four kinds (see core.Note): footnote, endnote,
+annotation, comment. WordStar itself only ever PRINTED the first three --
+comments are an author-only aside, never rendered by WordStar at all (spec-
+documented). Text/Markdown/HTML/RTF have no notion of "don't print this" the
+way WordStar did, so that behavior has to be modeled explicitly here instead
+of falling out of the parse for free.
+"""
+from .core import parse
+from .emit import get_emitter, DEFAULT_NOTE_KINDS, ALL_NOTE_KINDS, select_notes
+
+__all__ = ['convert', 'select_notes', 'DEFAULT_NOTE_KINDS', 'ALL_NOTE_KINDS']
+
+
+def convert(data: bytes, to: str = 'markdown', mode: str = 'modern',
+            encoding: str = 'cp437', notes=DEFAULT_NOTE_KINDS, **options) -> str:
+    """One-call API: bytes in, converted string out.
+
+    `notes` selects which note kinds appear in the output: any iterable of
+    'footnote' / 'endnote' / 'annotation' / 'comment' (the strings match
+    Note.kind exactly). Default is DEFAULT_NOTE_KINDS -- footnotes, endnotes,
+    annotations, matching what WordStar itself would have printed. Comments
+    are excluded by default; pass a set that includes 'comment' (or the
+    ALL_NOTE_KINDS constant) to surface them -- e.g. a rescue tool run on
+    request to recover hidden author asides. Unrecognised kind strings are
+    silently ignored rather than raising, so a caller (CLI flag, a Swift/
+    macOS picker's checkbox state) can pass a fixed set without first
+    validating spelling against this library's kind names.
+
+    This is forwarded to the emitter as the same `notes=` keyword an emitter
+    accepts when called directly (bypassing convert()); third-party emitters
+    that don't know about it simply ignore it via **options, per the
+    EXTENDING.md contract.
+    """
+    return get_emitter(to)['fn'](parse(data, encoding=encoding), mode, notes=notes, **options)