ctrl-kd

Convert WordStar-era files to modern formats. ^KD: save and done.

ctrl-kd reads WordStar 4 documents, WordStar 5–7 documents, and WordStar print-to-disk files (the printer byte stream, captured to a file — a distinct format most converters mangle), and writes plain text, Markdown, HTML, RTF, or PDF (typewriter-set on the built-in Courier fonts — no dependencies, the page as it would have printed).

$ ctrl-kd ESSAY.WS                      # -> ESSAY.md
$ 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?

Why another converter?

Existing tools each lose something. Fed a WordStar 4 file, converters written for WS7 delete the last letter of every word (WS4 set bit 7 on it). Most delete soft returns outright — Jon Michaels + March 6, 1992 becomes Jon MichaelsMarch 6, 1992 — which also destroys every poem, because poem lines end in soft returns too. And print-to-disk files aren't WordStar documents at all, so feeding them to a WordStar converter produces stray superscripts and garbage.

ctrl-kd was built by converting a real 1987–1992 corpus (high-school and college papers, poems, stories — WordStar 4 on DOS, dot-matrix printer) and verifying against surviving period printouts of the same documents. Its rules are empirical:

• Detection by content, never by extension. WS4 vs WS5+ vs print stream vs plain text vs binary, with the evidence shown in --diagnose.
• The wrap test. WordStar wrapped only when the next word didn't fit. So a soft return where the next word would have fit (strictly — WordStar wrapped even on an exact-margin fit) is a deliberate break: a poem line, a heading. Everything else is word wrap and joins with a space. The margin is estimated from the 90th percentile of soft-wrapped line lengths (floor 65, the default).
• Break runs. Soft/hard return runs containing a hard return and a blank line are paragraph breaks; a lone hard return is the author's deliberate line break. Double-spaced documents (blank soft lines between every line) collapse automatically.
• Ruler lines mean columns. A .rr----!---- dot line defines tab stops; the document's alignment is space-built and only survives fixed-width. Such documents render printed in every mode.
• Print streams render verbatim — they ARE the printed page — with printer style codes decoded (superscript/underline/italic/bold pairs; table in core.PRINT_CODES, derived from a late-80s dot-matrix driver and overridable).
• 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.

Modes

• --mode modern (default): reflowed paragraphs, semantic markup, deliberate line breaks kept.
• --mode printed: every line as laid out, fixed-width, .pa/form-feed page breaks honored — how it came off the printer.

Install

Straight from GitHub (not yet on PyPI):

$ pipx install git+https://github.com/jonmichaels/ctrl-kd

or pip install git+https://github.com/jonmichaels/ctrl-kd into an environment of your choice. Python ≥ 3.9, no dependencies. Library API: ctrlkd.convert(data, to='html').

Adding an output format

An output format is one function over the parsed document — register it with the @ctrlkd.emitter decorator, or ship it as a pip-installable plugin via the ctrlkd.emitters entry-point group and it appears in the CLI automatically. EXTENDING.md has the IR contract, a complete worked example (BBCode in ~40 lines), and a checklist.

Lineage

Standing on the shoulders of the tools and documentation that kept WordStar readable: Yohanes Nugroho's WS-CON, Michael Petrie's English port, the wsconvert project, Robert J. Sawyer's WordStar archive, and the WordStar format documentation community. Behaviors were studied and reimplemented; no code was copied. The development corpus is personal and is not distributed — tests use synthetic fixtures that encode the same behaviors.

Credits

Written by Jon Michaels — whose 1987–1992 WordStar files, and the need to read them again, are the reason this exists — with Athena (Claude, Anthropic) as co-author: the byte archaeology, the wrap test, and the implementation grew out of a joint effort to recover those disks. Every commit carries the co-author trailer.

License

MIT © Jon Michaels