ctrl-kd 4.0.0__tar.gz → 4.5.0__tar.gz

ctrl_kd-4.5.0/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: ctrl-kd
+Version: 4.5.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
+Project-URL: Homepage, https://github.com/jonmichaels/ctrl-kd
+Keywords: wordstar,converter,retrocomputing,archive,dos
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Text Processing :: Filters
+Classifier: Topic :: System :: Archiving
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+```
+        __       __      __       __
+  _____/ /______/ /     / /______/ /
+ / ___/ __/ ___/ /_____/ //_/ __  /
+/ /__/ /_/ /  / /_____/ ,< / /_/ /
+\___/\__/_/  /_/     /_/|_|\__,_/
+```
+# ctrl-kd
+
+Convert WordStar for DOS v4-v7 files to modern formats. **^KD: save and done.**
+
+`ctrl-kd` reads WordStar for DOS documents, and WordStar print stream files, 
+and writes plain text, Markdown, HTML, RTF, or PDF (set on a viewer's 
+built-in base-14 fonts — no dependencies, nothing embedded, the page as it 
+would have printed: printed mode follows the document's own font blocks and 
+its own layout arithmetic, while modern mode is the same document reflowed 
+for today: its fonts, headers, and footnotes all carried.
+
+```console
+$ ctrl-kd ESSAY.WS                      # -> ESSAY.rtf: modern reflow, the
+                                        #    document's own fonts carried
+$ ctrl-kd --mode printed LETTER.WS      # -> LETTER.pdf: the 1990 facsimile
+$ ctrl-kd ESSAY.WS -t md                # modern markdown instead
+$ ctrl-kd ESSAY.WS -t html -t rtf       # multiple formats
+$ ctrl-kd --page-settings sawyer X.WS   # a known machine's page defaults
+$ 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
+$ ctrl-kd --samples DIR                 # write 4 bundled public-domain sample .WS files into DIR
+```
+
+## Modes
+
+* `--mode modern` (default; bare runs produce RTF): the document brought to a
+  modern audience — reflowed, its own fonts and styles carried, footnotes at
+  the page bottom, gaps the file never specified filled with today's
+  conventions (a comfortable serif at reading size, one-inch margins).
+* `--mode printed` (bare runs produce PDF): every line as laid out, on the
+  era's own page — how it came off the printer. Gaps are filled with 1990's
+  conventions instead; `--page-settings` supplies a particular machine's.
+
+More information: **[FAQ.md](FAQ.md)**, and **[ERAS.md](ERAS.md)**.
+
+## Install
+
+```console
+$ brew install jonmichaels/tap/ctrl-kd     # macOS / Linuxbrew
+$ pipx install ctrl-kd                     # or: pip install ctrl-kd
+```
+
+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](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)** — macOS viewer and converter plus QuickLook extension.
+Includes a Swift command line utility.
+
+## Lineage
+
+I wanted to be able to see the 70-some WordStar 4 files I had from junior high 
+and high school. In about an hour and half my agent had my files looking 
+pretty good. And then I fell down the research rabbit hole...
+
+`ctrl-kd` wouldn't have been possible without 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. 
+
+My own test files are personal and are not distributed — this repo's tests use 
+synthetic fixtures and some public domain docs I retyped in WordStar 4 and 
+WordStar 7 in DOSBox-X, plus Robert J. Sawyer's public WS7 archive (opt-in, 
+`pytest -m sawyer`; see `tests/SAWYER-CORPUS.md`) you can run your own tests
+against that if you have a copy.
+
+## 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.

ctrl_kd-4.5.0/README.md

@@ -0,0 +1,87 @@
+```
+        __       __      __       __
+  _____/ /______/ /     / /______/ /
+ / ___/ __/ ___/ /_____/ //_/ __  /
+/ /__/ /_/ /  / /_____/ ,< / /_/ /
+\___/\__/_/  /_/     /_/|_|\__,_/
+```
+# ctrl-kd
+
+Convert WordStar for DOS v4-v7 files to modern formats. **^KD: save and done.**
+
+`ctrl-kd` reads WordStar for DOS documents, and WordStar print stream files, 
+and writes plain text, Markdown, HTML, RTF, or PDF (set on a viewer's 
+built-in base-14 fonts — no dependencies, nothing embedded, the page as it 
+would have printed: printed mode follows the document's own font blocks and 
+its own layout arithmetic, while modern mode is the same document reflowed 
+for today: its fonts, headers, and footnotes all carried.
+
+```console
+$ ctrl-kd ESSAY.WS                      # -> ESSAY.rtf: modern reflow, the
+                                        #    document's own fonts carried
+$ ctrl-kd --mode printed LETTER.WS      # -> LETTER.pdf: the 1990 facsimile
+$ ctrl-kd ESSAY.WS -t md                # modern markdown instead
+$ ctrl-kd ESSAY.WS -t html -t rtf       # multiple formats
+$ ctrl-kd --page-settings sawyer X.WS   # a known machine's page defaults
+$ 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
+$ ctrl-kd --samples DIR                 # write 4 bundled public-domain sample .WS files into DIR
+```
+
+## Modes
+
+* `--mode modern` (default; bare runs produce RTF): the document brought to a
+  modern audience — reflowed, its own fonts and styles carried, footnotes at
+  the page bottom, gaps the file never specified filled with today's
+  conventions (a comfortable serif at reading size, one-inch margins).
+* `--mode printed` (bare runs produce PDF): every line as laid out, on the
+  era's own page — how it came off the printer. Gaps are filled with 1990's
+  conventions instead; `--page-settings` supplies a particular machine's.
+
+More information: **[FAQ.md](FAQ.md)**, and **[ERAS.md](ERAS.md)**.
+
+## Install
+
+```console
+$ brew install jonmichaels/tap/ctrl-kd     # macOS / Linuxbrew
+$ pipx install ctrl-kd                     # or: pip install ctrl-kd
+```
+
+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](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)** — macOS viewer and converter plus QuickLook extension.
+Includes a Swift command line utility.
+
+## Lineage
+
+I wanted to be able to see the 70-some WordStar 4 files I had from junior high 
+and high school. In about an hour and half my agent had my files looking 
+pretty good. And then I fell down the research rabbit hole...
+
+`ctrl-kd` wouldn't have been possible without 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. 
+
+My own test files are personal and are not distributed — this repo's tests use 
+synthetic fixtures and some public domain docs I retyped in WordStar 4 and 
+WordStar 7 in DOSBox-X, plus Robert J. Sawyer's public WS7 archive (opt-in, 
+`pytest -m sawyer`; see `tests/SAWYER-CORPUS.md`) you can run your own tests
+against that if you have a copy.
+
+## 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.

ctrl_kd-4.5.0/pyproject.toml

@@ -0,0 +1,61 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ctrl-kd"
+dynamic = ["version"]
+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"}
+authors = [{name = "Jon Michaels"}]
+requires-python = ">=3.9"
+keywords = ["wordstar", "converter", "retrocomputing", "archive", "dos"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Environment :: Console",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Text Processing :: Filters",
+    "Topic :: System :: Archiving",
+]
+
+[project.urls]
+Homepage = "https://github.com/jonmichaels/ctrl-kd"
+
+[project.scripts]
+ctrl-kd = "ctrlkd.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.dynamic]
+# single source of truth: src/ctrlkd/__init__.py __version__ -- the 4.0.0
+# release shipped with pyproject still saying 3.0.0 because the version
+# lived in two places and the bump hit one (2026-08-06); never again
+version = {attr = "ctrlkd.__version__"}
+
+[tool.setuptools.package-data]
+# The four bundled public-domain sample documents (see samples/README.md and
+# `ctrl-kd --samples DIR`) travel with the wheel/sdist as package data.
+ctrlkd = ["samples/*.WS"]
+
+[tool.pytest.ini_options]
+# Two-tier test architecture (K1, 2026-08-26; tier 3/private relocated out
+# of this public repo entirely -- see README). Bare `pytest` must run ONLY
+# tier 1 (tests/test_samples.py and every other test with no marker below)
+# -- green, complete, zero skips, no environment required. Tier 2 is
+# DESELECTED here, not skipped: it never even collects into the report, so
+# a bare run's summary line is an honest denominator.
+#
+# Arming (see tests/sawyer_fixture.py, conftest.py):
+#   sawyer   CTRLKD_SAWYER_ARCHIVE=/path   (legacy alias: CTRLKD_CORPUS_SOURCE)
+#
+# tools/run-full-suite.sh overrides this filter (`-o addopts=""`) for an
+# armed run, where an unarmed gate FAILS instead of silently not running --
+# see that script's own header for why.
+testpaths = ["tests"]
+markers = [
+    "sawyer: opt-in tier 2 -- an explicit, committed list of documents from Robert J. Sawyer's public WordStar 7 archive (arm with CTRLKD_SAWYER_ARCHIVE)",
+]
+addopts = "-m \"not sawyer\""

ctrl_kd-4.5.0/src/ctrl_kd.egg-info/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: ctrl-kd
+Version: 4.5.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
+Project-URL: Homepage, https://github.com/jonmichaels/ctrl-kd
+Keywords: wordstar,converter,retrocomputing,archive,dos
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Text Processing :: Filters
+Classifier: Topic :: System :: Archiving
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+```
+        __       __      __       __
+  _____/ /______/ /     / /______/ /
+ / ___/ __/ ___/ /_____/ //_/ __  /
+/ /__/ /_/ /  / /_____/ ,< / /_/ /
+\___/\__/_/  /_/     /_/|_|\__,_/
+```
+# ctrl-kd
+
+Convert WordStar for DOS v4-v7 files to modern formats. **^KD: save and done.**
+
+`ctrl-kd` reads WordStar for DOS documents, and WordStar print stream files, 
+and writes plain text, Markdown, HTML, RTF, or PDF (set on a viewer's 
+built-in base-14 fonts — no dependencies, nothing embedded, the page as it 
+would have printed: printed mode follows the document's own font blocks and 
+its own layout arithmetic, while modern mode is the same document reflowed 
+for today: its fonts, headers, and footnotes all carried.
+
+```console
+$ ctrl-kd ESSAY.WS                      # -> ESSAY.rtf: modern reflow, the
+                                        #    document's own fonts carried
+$ ctrl-kd --mode printed LETTER.WS      # -> LETTER.pdf: the 1990 facsimile
+$ ctrl-kd ESSAY.WS -t md                # modern markdown instead
+$ ctrl-kd ESSAY.WS -t html -t rtf       # multiple formats
+$ ctrl-kd --page-settings sawyer X.WS   # a known machine's page defaults
+$ 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
+$ ctrl-kd --samples DIR                 # write 4 bundled public-domain sample .WS files into DIR
+```
+
+## Modes
+
+* `--mode modern` (default; bare runs produce RTF): the document brought to a
+  modern audience — reflowed, its own fonts and styles carried, footnotes at
+  the page bottom, gaps the file never specified filled with today's
+  conventions (a comfortable serif at reading size, one-inch margins).
+* `--mode printed` (bare runs produce PDF): every line as laid out, on the
+  era's own page — how it came off the printer. Gaps are filled with 1990's
+  conventions instead; `--page-settings` supplies a particular machine's.
+
+More information: **[FAQ.md](FAQ.md)**, and **[ERAS.md](ERAS.md)**.
+
+## Install
+
+```console
+$ brew install jonmichaels/tap/ctrl-kd     # macOS / Linuxbrew
+$ pipx install ctrl-kd                     # or: pip install ctrl-kd
+```
+
+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](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)** — macOS viewer and converter plus QuickLook extension.
+Includes a Swift command line utility.
+
+## Lineage
+
+I wanted to be able to see the 70-some WordStar 4 files I had from junior high 
+and high school. In about an hour and half my agent had my files looking 
+pretty good. And then I fell down the research rabbit hole...
+
+`ctrl-kd` wouldn't have been possible without 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. 
+
+My own test files are personal and are not distributed — this repo's tests use 
+synthetic fixtures and some public domain docs I retyped in WordStar 4 and 
+WordStar 7 in DOSBox-X, plus Robert J. Sawyer's public WS7 archive (opt-in, 
+`pytest -m sawyer`; see `tests/SAWYER-CORPUS.md`) you can run your own tests
+against that if you have a copy.
+
+## 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.

ctrl_kd-4.5.0/src/ctrl_kd.egg-info/SOURCES.txt

@@ -0,0 +1,63 @@
+LICENSE
+README.md
+pyproject.toml
+src/ctrl_kd.egg-info/PKG-INFO
+src/ctrl_kd.egg-info/SOURCES.txt
+src/ctrl_kd.egg-info/dependency_links.txt
+src/ctrl_kd.egg-info/entry_points.txt
+src/ctrl_kd.egg-info/top_level.txt
+src/ctrlkd/__init__.py
+src/ctrlkd/afm.py
+src/ctrlkd/cli.py
+src/ctrlkd/convert.py
+src/ctrlkd/core.py
+src/ctrlkd/emit.py
+src/ctrlkd/fontmap.py
+src/ctrlkd/info.py
+src/ctrlkd/layout.py
+src/ctrlkd/pdf.py
+src/ctrlkd/pictures.py
+src/ctrlkd/pix.py
+src/ctrlkd/piximg.py
+src/ctrlkd/symbolmap.py
+src/ctrlkd/typestyles.py
+src/ctrlkd/writer.py
+src/ctrlkd/wschange.py
+src/ctrlkd/samples/LYING.WS
+src/ctrlkd/samples/OCAPTAIN.WS
+src/ctrlkd/samples/TWAINLET.WS
+src/ctrlkd/samples/WARPRAYR.WS
+tests/test_ctrlkd.py
+tests/test_endnote_leading_gap.py
+tests/test_fidelity_gate.py
+tests/test_flags_toc_inline.py
+tests/test_glyph_aspect.py
+tests/test_layout_marks.py
+tests/test_lj6dtp_bullet_glyph.py
+tests/test_lj6dtp_char_substitution.py
+tests/test_lj6dtp_colour_restore.py
+tests/test_lj6dtp_heading_face.py
+tests/test_lj6dtp_hp_patterns.py
+tests/test_lj6dtp_legend_line_spacing.py
+tests/test_lj6dtp_pcl_rectangles.py
+tests/test_lj6dtp_shading_table_rules.py
+tests/test_lj6dtp_table_rule_weight.py
+tests/test_modern_box_regions.py
+tests/test_modern_line_spacing.py
+tests/test_modern_lint.py
+tests/test_note_rulings_20260824.py
+tests/test_pictures.py
+tests/test_pix.py
+tests/test_polarity_gate.py
+tests/test_printed_fidelity.py
+tests/test_samples.py
+tests/test_sawyer_corpus.py
+tests/test_screenplay_detection.py
+tests/test_screenplay_pdf.py
+tests/test_screenplay_rendering.py
+tests/test_sentence_spacing_n9.py
+tests/test_style_leading.py
+tests/test_verse_quote_couplet.py
+tests/test_verse_spacing.py
+tests/test_writer.py
+tests/test_wschange.py

{ctrl_kd-4.0.0 → ctrl_kd-4.5.0}/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.0.0'
+__version__ = '4.5.0'

{ctrl_kd-4.0.0 → ctrl_kd-4.5.0}/src/ctrlkd/cli.py

@@ -7,8 +7,9 @@
     ctrl-kd --page-settings sawyer X.WS    # a known machine's page defaults
     ctrl-kd --diagnose MYSTERY.FIL         # what IS this file?
     ctrl-kd -t text -t html -d out/ *.WS   # batch, multiple formats
+    ctrl-kd --samples DIR                  # write the 4 bundled sample .WS files into DIR
 """
-import argparse, json, os, sys
+import argparse, importlib.resources, json, os, shutil, sys
 
 BANNER = r"""        __       __      __       __
   _____/ /______/ /     / /______/ /
@@ -21,7 +22,7 @@ BANNER = r"""        __       __      __       __
 # because the name never changes; no .flf machinery needed.
 
 
-from . import core, emit
+from . import core, emit, pictures
 from .convert import DEFAULT_NOTE_KINDS   # module attr, not the re-exported convert()
 
 def diagnose(path, data):
@@ -30,6 +31,26 @@ def diagnose(path, data):
     from .info import document_info
     return document_info(data, path=path)
 
+# The four public-domain WordStar sample documents (see samples/README.md at
+# the repo root for credits) -- shipped as package data (src/ctrlkd/samples/,
+# [tool.setuptools.package-data] in pyproject.toml) so `--samples` works from
+# an installed wheel, not just a checkout.
+SAMPLE_NAMES = ['LYING.WS', 'OCAPTAIN.WS', 'TWAINLET.WS', 'WARPRAYR.WS']
+
+
+def write_samples(outdir):
+    """Write the four bundled sample documents into outdir. Returns the list
+    of paths written."""
+    os.makedirs(outdir, exist_ok=True)
+    written = []
+    samples_dir = importlib.resources.files('ctrlkd').joinpath('samples')
+    for name in SAMPLE_NAMES:
+        dest = os.path.join(outdir, name)
+        with importlib.resources.as_file(samples_dir.joinpath(name)) as src:
+            shutil.copyfile(src, dest)
+        written.append(dest)
+    return written
+
 def main(argv=None):
     emit.load_plugins()          # third-party emitters (ctrlkd.emitters entry points)
     ap = argparse.ArgumentParser(
@@ -41,7 +62,12 @@ def main(argv=None):
     from . import __version__
     ap.add_argument('--version', action='version',
                     version=BANNER + f'\nctrl-kd {__version__}')
-    ap.add_argument('files', nargs='+', help='input file(s)')
+    ap.add_argument('files', nargs='*', help='input file(s) (not required '
+                    'with --samples)')
+    ap.add_argument('--samples', metavar='DIR',
+                    help='write the four bundled public-domain WordStar '
+                         'sample documents into DIR (see samples/README.md); '
+                         'no conversion, files are not required')
     ap.add_argument('-t', '--to', action='append', choices=emit.formats(),
                     help='output format (repeatable). Default follows the '
                          'mode: modern -> rtf (the full-fidelity living '
@@ -103,6 +129,70 @@ def main(argv=None):
     ap.add_argument('--no-styles', action='store_true',
                     help='omit paragraph-style pass-through (HTML classes + '
                          'generated CSS, RTF stylesheet) from the output')
+    ap.add_argument('--headers', choices=('on', 'off'), default='on',
+                    help='headers, footers, and page numbers in the paged '
+                         'surfaces (Printed/Native PDF and RTF). Default: on')
+    ap.add_argument('--page-numbers', choices=('auto', 'on', 'off'),
+                    default='auto',
+                    help="WordStar's own AUTOMATIC page number -- the one "
+                         '.pc positions, a separate mechanism from a # the '
+                         'author placed inside a real .he/.fo (that always '
+                         'prints, unaffected by this flag). Printed PDF '
+                         'only. auto (DEFAULT): the document\'s own dot '
+                         'commands decide -- .pn/.pg turn it on, .op turns '
+                         'it off, exactly like real WordStar; a document '
+                         'that never touches any of the four gets no '
+                         'number, byte-identical to before this flag '
+                         'existed. on: force stock default numbering '
+                         '(bottom-center; .pc repositions it) even on a '
+                         'silent document. off: suppress it unconditionally. '
+                         'A declared footer always pre-empts it, in every '
+                         'mode (WSFORMAT.WS: "active only when the footers '
+                         'are not in use"). --headers off also suppresses '
+                         'it, per --headers\' own documented scope.')
+    ap.add_argument('--line-numbers', choices=('on', 'off'), default='on',
+                    help="the document's own .l# line-number gutter in the "
+                         'paged surfaces (Printed/Native PDF and RTF); no '
+                         'effect on a document that never set .l#. Default: on')
+    ap.add_argument('--sentence-spacing', choices=('auto', 'keep', 'single'),
+                    default='auto',
+                    help='the typewriter double space after a sentence-'
+                         "ending '.', '?', or '!'. auto (DEFAULT): follows "
+                         '--mode -- modern converts it to a single space '
+                         '(the modern typographic convention); printed '
+                         'keeps the document exactly as authored (period '
+                         'fidelity). keep/single force that choice '
+                         'regardless of mode. A simple textual rule, no '
+                         'abbreviation detection: "e.g.  x" collapses like '
+                         'a real sentence end. Markdown never emits a '
+                         'trailing double space from this either way (that '
+                         "is CommonMark's own hard-break marker) -- unrelated "
+                         'to this flag, always on.')
+    ap.add_argument('--toc', choices=('on', 'off'), default='off',
+                    help='compile a Table of Contents (.tc) and Index (.ix) '
+                         'section at the document end, in every format; the '
+                         'two paged surfaces (Printed PDF and RTF) resolve '
+                         'each entry to a real page number, every other '
+                         'format lists entries without one. Default: off')
+    ap.add_argument('--inline-styling', choices=('on', 'off'), default='on',
+                    help='inline colour (^A) and font-size (^B... a symmetric '
+                         'type-2 font block) changes the author placed mid-'
+                         'text -- RTF gets \\cf from a 16-colour screen '
+                         'palette and \\fsN; HTML gets a span with color/'
+                         'font-size. Default: on')
+    ap.add_argument('--pictures', choices=('off', 'embed', 'export'), default='embed',
+                    help='WS5+ PIX image references (register, "PIX images '
+                         'RULED IN"). embed (DEFAULT): RTF/PDF native '
+                         'embedding, HTML data URI, MD exports files + a '
+                         'one-line stderr note (MD has no true embed). '
+                         'export: PNG files under <docname>-images/ beside '
+                         'the output, relative links from HTML/MD; RTF/PDF '
+                         'still embed (no portable reference mechanism) AND '
+                         'the PNGs are also written. off: the plain '
+                         '[image: NAME] placeholder, as before this flag '
+                         'existed. A missing/unreadable .PIX is reported on '
+                         'stderr (name + probed locations) and never fails '
+                         'the conversion; the placeholder is kept either way.')
     ap.add_argument('--no-notes', action='store_true',
                     help='omit footnotes, endnotes and annotations from the output')
     ap.add_argument('--comments', action='store_true',
@@ -112,6 +202,12 @@ def main(argv=None):
                     help='report what the file is (variant, margin, dot commands, '
                          'unknown codes) as JSON; no conversion')
     a = ap.parse_args(argv)
+    if a.samples:
+        for dest in write_samples(a.samples):
+            print(f'-> {dest}', file=sys.stderr)
+        return 0
+    if not a.files:
+        ap.error('the following arguments are required: files')
     mode_explicit = a.mode is not None
     a.mode = a.mode or 'modern'
     # The default format follows the mode (ruling 2026-08-05): bare modern =
@@ -223,11 +319,21 @@ def main(argv=None):
             doc.meta['page'] = core.effective_page(doc.meta['page'],
                                                    page_settings)
         base = os.path.splitext(os.path.basename(path))[0]
+        # Round 19 (PIX images RULED IN, ledger PIX row): resolved/decoded
+        # ONCE per document, reused across every requested format (each
+        # PIX file is read and decoded at most once regardless of how
+        # many -t flags this run carries). `path` is the real filesystem
+        # location resolution searches near -- the CLI always has one; a
+        # library caller without a real path passes None (every tag then
+        # reports 'unresolved', ctrlkd.pictures' own documented behavior).
+        pix_results = (pictures.resolve_document_pictures(doc, path)
+                       if doc.graphics else [])
+        if pix_results and a.pictures != 'off':
+            # 'off' means the user doesn't want the feature at all -- no
+            # point reporting misses for pictures nothing will render.
+            pictures.report_misses(pix_results, path, path)
         for fmt in formats:
             reg = emit.get_emitter(fmt)
-            out = reg['fn'](doc, a.mode, title=base, notes=notes,
-                            styles=not a.no_styles, fonts_target=a.fonts,
-                            note_refs=a.note_refs)
             if a.output:
                 dest = a.output
             else:
@@ -235,6 +341,44 @@ def main(argv=None):
                                     base + reg['ext'])
                 if a.outdir:
                     os.makedirs(a.outdir, exist_ok=True)
+            # --pictures export writes PNG files beside the output for
+            # every applicable format; MD's own embed mode degrades to
+            # the same export-and-link behavior (ruled: MD has no true
+            # embed) -- ONE stderr note for that degradation, here, not
+            # inside emit_markdown (library functions stay silent, same
+            # convention as every other emit_* degradation this session).
+            image_links = None
+            # MD's embed-degrades-to-export only matters in MODERN mode --
+            # a Printed-mode MD body is emit_text's fenced facsimile
+            # (never consults image_links at all, by design: a fence is
+            # the emitter's own "verbatim" promise), so exporting files
+            # and printing the degradation note for it would be pure
+            # waste, not a correctness issue but a confusing one.
+            need_export = (a.pictures == 'export'
+                          or (fmt == 'md' and a.pictures == 'embed'
+                              and a.mode == 'modern'))
+            if need_export and any(r.ok for r in pix_results):
+                images_dir = os.path.join(os.path.dirname(dest) or '.',
+                                          base + '-images')
+                written = pictures.write_export_images(pix_results, images_dir)
+                image_links = {i: f'{base}-images/{name}'
+                               for i, name in written.items()}
+                if fmt == 'md' and a.pictures == 'embed' and written:
+                    print(f'ctrl-kd: {path}: Markdown has no true image '
+                          f'embedding -- exporting {len(written)} PNG '
+                          f"file(s) to {os.path.basename(images_dir)}/ "
+                          f'and linking to them instead (degradation per '
+                          f'the pictures flag ruling)', file=sys.stderr)
+            out = reg['fn'](doc, a.mode, title=base, notes=notes,
+                            styles=not a.no_styles, fonts_target=a.fonts,
+                            note_refs=a.note_refs, headers=a.headers == 'on',
+                            line_numbers=a.line_numbers == 'on',
+                            toc=a.toc == 'on',
+                            inline_styling=a.inline_styling == 'on',
+                            pictures=a.pictures, pix_results=pix_results,
+                            image_links=image_links,
+                            page_numbers=a.page_numbers,
+                            sentence_spacing=a.sentence_spacing)
             if isinstance(out, bytes):           # binary formats (e.g. pdf)
                 with open(dest, 'wb') as f:
                     f.write(out)